react-native-live-widgets 0.0.0-stage → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (59) hide show
  1. package/CHANGELOG.md +13 -0
  2. package/LICENSE +21 -0
  3. package/README.md +221 -2
  4. package/android/build.gradle +49 -0
  5. package/android/src/main/AndroidManifest.xml +38 -0
  6. package/android/src/main/java/com/reactnativeliveactivity/bridge/LiveActivityModule.kt +440 -0
  7. package/android/src/main/java/com/reactnativeliveactivity/bridge/LiveActivityPackage.kt +17 -0
  8. package/android/src/main/java/com/reactnativeliveactivity/liveactivity/LiveActivityHeadlessTaskService.kt +24 -0
  9. package/android/src/main/java/com/reactnativeliveactivity/liveactivity/LiveActivityNotifier.kt +410 -0
  10. package/android/src/main/java/com/reactnativeliveactivity/liveactivity/LiveActivityReceiver.kt +67 -0
  11. package/android/src/main/java/com/reactnativeliveactivity/renderer/DynamicNodeRegistry.kt +64 -0
  12. package/android/src/main/java/com/reactnativeliveactivity/renderer/DynamicWidgetCanvasRenderer.kt +1223 -0
  13. package/android/src/main/java/com/reactnativeliveactivity/storage/DynamicWidgetImageCache.kt +120 -0
  14. package/android/src/main/java/com/reactnativeliveactivity/storage/DynamicWidgetStateStore.kt +281 -0
  15. package/android/src/main/java/com/reactnativeliveactivity/widgets/DynamicHomeScreenWidgetProvider.kt +229 -0
  16. package/android/src/main/res/layout/rn_live_widget_host.xml +113 -0
  17. package/android/src/main/res/xml/rn_live_widget_info.xml +14 -0
  18. package/assets/dashboard_features.png +0 -0
  19. package/assets/dynamic_island_expanded.png +0 -0
  20. package/assets/home_widget_interactive.png +0 -0
  21. package/assets/lock_screen_live_activity.png +0 -0
  22. package/cli/setup.js +94 -0
  23. package/docs/GUIDE-EN.md +804 -0
  24. package/docs/GUIDE-VI.md +802 -0
  25. package/docs/widgets.md +52 -0
  26. package/ios/Bridge/LiveActivityModule.m +105 -0
  27. package/ios/Bridge/LiveActivityModule.swift +957 -0
  28. package/ios/Intents/DynamicWidgetActionIntent.swift +38 -0
  29. package/ios/Models/DynamicActivityAttributes.swift +22 -0
  30. package/ios/Models/DynamicLayoutModels.swift +243 -0
  31. package/ios/Renderer/ColorHexExtension.swift +49 -0
  32. package/ios/Renderer/DynamicNodeRegistry.swift +54 -0
  33. package/ios/Renderer/DynamicNodeView.swift +1060 -0
  34. package/ios/Storage/DynamicWidgetImageCache.swift +137 -0
  35. package/ios/Storage/DynamicWidgetStateStore.swift +162 -0
  36. package/ios/Widgets/DynamicHomeScreenWidget.swift +435 -0
  37. package/ios/Widgets/DynamicLiveActivityWidget.swift +79 -0
  38. package/lib/builder.d.ts +60 -0
  39. package/lib/builder.d.ts.map +1 -0
  40. package/lib/builder.js +296 -0
  41. package/lib/builder.js.map +1 -0
  42. package/lib/dispatcher.d.ts +16 -0
  43. package/lib/dispatcher.d.ts.map +1 -0
  44. package/lib/dispatcher.js +23 -0
  45. package/lib/dispatcher.js.map +1 -0
  46. package/lib/index.d.ts +199 -0
  47. package/lib/index.d.ts.map +1 -0
  48. package/lib/index.js +634 -0
  49. package/lib/index.js.map +1 -0
  50. package/lib/types.d.ts +489 -0
  51. package/lib/types.d.ts.map +1 -0
  52. package/lib/types.js +10 -0
  53. package/lib/types.js.map +1 -0
  54. package/package.json +68 -4
  55. package/react-native-live-widgets.podspec +38 -0
  56. package/src/builder.ts +409 -0
  57. package/src/dispatcher.ts +25 -0
  58. package/src/index.ts +681 -0
  59. package/src/types.ts +595 -0
package/CHANGELOG.md ADDED
@@ -0,0 +1,13 @@
1
+ # Changelog
2
+
3
+ All notable changes to `react-native-live-widgets` will be documented in this file.
4
+
5
+ ## [1.0.0] - 2026-11-15
6
+ ### Added
7
+ - **Declarative UI Engine (`UI.*`)**: Build Home Screen Widgets (`small`, `medium`, `large`) and Live Activities (`lockScreen`, `dynamicIsland`) 100% in React Native using `UI.VStack`, `UI.HStack`, `UI.Text`, `UI.Timer`, `UI.Progress` (`bar`, `segmented`, `circular`), `UI.Image`, and `UI.Button`.
8
+ - **Interactive Multi-Page & Checklist Widgets (iOS & Android)**: In-place page switching (`actionId: 'page:<id>'`, `'page:next'`, `'page:prev'`) and task checklist toggling (`actionId: 'toggle:<key>'`) via iOS 17+ `AppIntents` and Android `PendingIntent` hit zones.
9
+ - **Background API Auto-Sync (`Widget.setRemoteConfig`)**: Autonomous background HTTP JSON fetch and `{{field}}` template interpolation even when the main app is force-killed.
10
+ - **Multi-Source Image Loader & Cache (`UI.Image`)**: Remote `https://` URLs (auto-prefetched, downscaled to `360px` max dimension, and cached), `base64`, `filePath`, `assetName`, and `systemName` (SF Symbols / Android Vector mapping).
11
+ - **Unified Push Token Management**: `devicePushToken`, `pushToStartToken` (iOS 17.2+), and `activityUpdateToken` across iOS APNs and Android FCM.
12
+ - **CLI Setup Wizard**: `npx react-native-live-widgets init` for automatic iOS & Android project configuration.
13
+
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 vu-tran
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,222 @@
1
- # Temporary Holding Version
1
+ # react-native-live-widgets 🚀
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ <div align="center">
4
+
5
+ [![npm version](https://img.shields.io/badge/npm-v1.0.0-blue.svg?style=for-the-badge&logo=npm)](https://www.npmjs.com/package/react-native-live-widgets)
6
+ [![Platforms](https://img.shields.io/badge/Platforms-iOS%2016.1+%20|%20Android%2016-orange.svg?style=for-the-badge)](https://github.com/React-Native-Vu/react-native-live-widgets)
7
+ [![TypeScript](https://img.shields.io/badge/TypeScript-100%25-3178C6.svg?style=for-the-badge&logo=typescript)](https://www.typescriptlang.org/)
8
+ [![License](https://img.shields.io/badge/License-MIT-green.svg?style=for-the-badge)](LICENSE)
9
+
10
+ **The Ultimate All-in-One Engine for Live Activities, Dynamic Island, and Interactive Home Screen Widgets in Bare React Native.**
11
+
12
+ *Write 100% Declarative TypeScript. Render dynamically to Native SwiftUI & Android 2D Canvas without touching Xcode or Android Studio.*
13
+
14
+ [📖 English Guide](docs/GUIDE-EN.md) • [🇻🇳 Hướng dẫn Tiếng Việt](docs/GUIDE-VI.md) • [✨ Features](#-key-features) • [⚡ Quick Start](#-quick-start)
15
+
16
+ ---
17
+
18
+ </div>
19
+
20
+ ## 📸 Showcase & Demos
21
+
22
+ | Dynamic Island (Expanded) | Interactive Home Screen Widget | Lock Screen Live Activity |
23
+ |:-------------------------:|:------------------------------:|:-------------------------:|
24
+ | <img src="assets/dynamic_island_expanded.png" width="260" alt="Dynamic Island Expanded" /> | <img src="assets/home_widget_interactive.png" width="260" alt="Interactive Widget" /> | <img src="assets/lock_screen_live_activity.png" width="260" alt="Lock Screen Live Activity" /> |
25
+ | *Segmented Progress & Realtime Timer* | *Buttons & Bi-directional State Sync* | *Multi-card KPI & Status Dashboard* |
26
+
27
+ ---
28
+
29
+ ## 💡 Why `react-native-live-widgets`?
30
+
31
+ Until now, adding **Live Activities** or **Home Screen Widgets** to a React Native app required writing hundreds of lines of complex Swift, SwiftUI, and Kotlin code, managing App Groups, Darwin notifications, and separate native target builds.
32
+
33
+ `react-native-live-widgets` solves this with a **Declarative TypeScript UI DSL**:
34
+ - 🚫 **No SwiftUI / Kotlin coding required** for custom screens.
35
+ - 🎨 **100% Declarative UI in React Native (`UI.VStack`, `UI.HStack`, `UI.Text`, `UI.Button`, `UI.Progress`)**.
36
+ - ⚡ **Interactive Buttons**: Tap buttons on the Home Screen Widget to run native Swift extensions or wake up TypeScript handlers.
37
+ - 🔄 **Realtime Data Sync (`SharedStorage`)**: Single source of truth across Main App, Lock Screen, and Home Screen.
38
+ - 🌐 **Silent Background Remote API Sync**: Automatically fetch REST APIs and update Widgets even when the App is **Force-Killed**.
39
+ - 🤖 **Android Parity**: Supports Android 16+ Promoted Live Notifications and Home Screen AppWidgets.
40
+
41
+ ---
42
+
43
+ ## ✨ Key Features
44
+
45
+ ### 1. 🏝️ Dynamic Island & Lock Screen Live Activities (iOS 16.1+)
46
+ - **All Dynamic Island Modes**: `compactLeading`, `compactTrailing`, `minimal`, and `expanded`.
47
+ - **Realtime Timers & Progress**: Countdown timers, segmented progress bars, and battery/progress rings with zero battery drain.
48
+ - **Smart Dismissal Policies**: `immediate`, `afterDate`, or `default`.
49
+
50
+ ### 2. 📱 Interactive Home Screen Widgets (iOS WidgetKit & Android AppWidget)
51
+ - Supports **Small**, **Medium**, and **Large** widget families.
52
+ - **Multi-page & Tabs**: Switch tabs or carousel pages directly on the widget (`actionId: "page:next"`).
53
+ - **Checklist & Toggles**: Toggle checkboxes and switch states without opening the app (`actionId: "toggle:<key>"`).
54
+ - **Dark & Light Mode**: Declarative color tokens `{ light: '#FFF', dark: '#0F172A' }`.
55
+
56
+ ### 3. ⚡ Bi-directional Action Dispatcher (TypeScript + Native)
57
+ - Tap a widget button outside on the Home Screen to trigger a registered TypeScript function:
58
+ ```ts
59
+ LiveActivity.registerAction('action_checkin', async () => {
60
+ // Runs inside React Native JS engine!
61
+ });
62
+ ```
63
+ - **App-Killed Protection**: Native fallback ensures UI responds instantly and persists data even if the main app is terminated.
64
+
65
+ ### 4. 🌐 Background Remote API Sync (Zero Code Backend)
66
+ - Configure an API endpoint with `Widget.setRemoteConfig`:
67
+ ```ts
68
+ await Widget.setRemoteConfig('main', {
69
+ url: 'https://api.yourcompany.com/v1/shifts/current',
70
+ method: 'GET',
71
+ refreshIntervalMinutes: 15
72
+ }, APP_GROUP);
73
+ ```
74
+ - The native Extension fetches fresh JSON and dynamically replaces `{{variables}}` in your widget layout in the background.
75
+
76
+ ### 5. 🔔 APNs & FCM Token Management
77
+ - One-call retrieval for all push tokens:
78
+ ```ts
79
+ const tokens = await LiveActivity.getAllPushTokens();
80
+ // tokens.devicePushToken
81
+ // tokens.pushToStartToken (iOS 17.2+)
82
+ // tokens.activityUpdateToken
83
+ ```
84
+
85
+ ### 6. 🎵 Background Audio & Media Notification
86
+ - Integrated with `MPNowPlayingInfoCenter` on iOS and `MediaStyle` Notifications on Android for audio playback status.
87
+
88
+ ---
89
+
90
+ ## ⚡ Quick Start
91
+
92
+ ### 1. Installation
93
+
94
+ ```bash
95
+ npm install react-native-live-widgets
96
+ # or
97
+ yarn add react-native-live-widgets
98
+ ```
99
+
100
+ ### 2. Auto-Configuration CLI
101
+
102
+ Run the automated scaffolding script in your React Native project root:
103
+
104
+ ```bash
105
+ npx react-native-live-widgets init --group group.com.yourcompany.app
106
+ ```
107
+
108
+ This will automatically:
109
+ - Inject `NSSupportsLiveActivities` and `NSSupportsLiveActivitiesFrequentUpdates` into `Info.plist`.
110
+ - Scaffold the `LiveWidgetsExtension` bundle in your `ios/` folder.
111
+ - Configure `AndroidManifest.xml` with required notification permissions.
112
+
113
+ ### 3. Install Pods
114
+
115
+ ```bash
116
+ cd ios && pod install
117
+ ```
118
+
119
+ ---
120
+
121
+ ## 💻 Code Example
122
+
123
+ ### 1. Start a Live Activity with Dynamic Island
124
+
125
+ ```tsx
126
+ import { UI, LiveActivity } from 'react-native-live-widgets';
127
+
128
+ await LiveActivity.start({
129
+ activityId: 'order_1024',
130
+ dynamicIsland: {
131
+ compactLeading: UI.Image({ systemName: 'bag.fill', tintColor: '#10B981' }),
132
+ compactTrailing: UI.Text('15 phút', { color: '#10B981', fontWeight: 'bold' }),
133
+ minimal: UI.Image({ systemName: 'bag.fill', tintColor: '#10B981' }),
134
+ expanded: UI.VStack(
135
+ { padding: 14, spacing: 8 },
136
+ UI.HStack(
137
+ { justifyContent: 'spaceBetween' },
138
+ UI.Text('ĐƠN HÀNG #1024', { fontSize: 11, color: '#94A3B8' }),
139
+ UI.Badge({ text: 'Đang giao', backgroundColor: '#064E3B', textColor: '#6EE7B7' })
140
+ ),
141
+ UI.Text('Tài xế đang đến điểm giao', { fontSize: 15, fontWeight: 'bold', color: '#FFFFFF' }),
142
+ UI.Progress({
143
+ style: 'bar',
144
+ value: 0.75,
145
+ tintColor: '#10B981',
146
+ trackColor: '#334155'
147
+ })
148
+ )
149
+ },
150
+ lockScreen: UI.VStack(
151
+ { padding: 16, backgroundColor: '#0F172A' },
152
+ UI.Text('GIAO HÀNG TIẾT KIỆM', { fontSize: 11, color: '#38BDF8' }),
153
+ UI.Text('Dự kiến nhận lúc 11:30', { fontSize: 16, fontWeight: 'bold', color: '#FFFFFF' })
154
+ )
155
+ });
156
+ ```
157
+
158
+ ### 2. Update Home Screen Widgets
159
+
160
+ ```tsx
161
+ import { UI, Widget } from 'react-native-live-widgets';
162
+
163
+ const APP_GROUP = 'group.com.yourcompany.app';
164
+
165
+ await Widget.setLayout('main', {
166
+ small: UI.VStack(
167
+ { padding: 12, backgroundColor: '#0F172A' },
168
+ UI.Text('CA LÀM VIỆC', { fontSize: 10, color: '#94A3B8' }),
169
+ UI.Text('Ca sáng', { fontSize: 16, fontWeight: 'bold', color: '#FFFFFF' }),
170
+ UI.Spacer(),
171
+ UI.Button('Chấm công', {
172
+ actionId: 'action_checkin',
173
+ backgroundColor: '#10B981',
174
+ textColor: '#FFFFFF'
175
+ })
176
+ )
177
+ }, APP_GROUP);
178
+
179
+ await Widget.reloadAll();
180
+ ```
181
+
182
+ ---
183
+
184
+ ## 📊 Platform Feature Parity Matrix
185
+
186
+ | Feature | iOS 16.1+ | Android (API 24 - 36) |
187
+ | :--- | :---: | :---: |
188
+ | **Declarative UI Engine (`UI.*`)** | SwiftUI dynamic tree | High-DPI Canvas 2D Bitmap |
189
+ | **Dynamic Island (All 4 layouts)** | ✅ Supported | 🔄 Mapped to Promoted Ongoing (Android 16+) |
190
+ | **Lock Screen Live Activity** | ✅ Supported | ✅ Ongoing Rich Notification |
191
+ | **Home Screen Widgets** | Small, Medium, Large | Resizable Grid AppWidgets |
192
+ | **Interactive Buttons** | iOS 17+ AppIntents | RemoteViews PendingIntent |
193
+ | **SharedStorage Data Sync** | App Group UserDefaults | Context SharedPreferences |
194
+ | **Remote API Silent Sync** | Background Timeline URLSession | WorkManager / Background Fetch |
195
+ | **Push Remote Updates** | Apple APNs Activity Tokens | Firebase Cloud Messaging (FCM) |
196
+
197
+ ---
198
+
199
+ ## 📚 Documentation
200
+
201
+ - 🇬🇧 **[Full English Developer Guide](docs/GUIDE-EN.md)**: Architecture, DSL specs, push notification server configuration, and best practices.
202
+ - 🇻🇳 **[Hướng dẫn Chi tiết bằng Tiếng Việt](docs/GUIDE-VI.md)**: Hướng dẫn tích hợp từng bước, thiết lập App Group, giải quyết lỗi thường gặp.
203
+
204
+ ---
205
+
206
+ ## 🤝 Contributing
207
+
208
+ Contributions are welcome! Please feel free to submit a Pull Request or open an Issue.
209
+
210
+ 1. Fork the Project.
211
+ 2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`).
212
+ 3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`).
213
+ 4. Push to the Branch (`git push origin feature/AmazingFeature`).
214
+ 5. Open a Pull Request.
215
+
216
+ ---
217
+
218
+ ## 📄 License
219
+
220
+ Distributed under the **MIT License**. See `LICENSE` for more information.
221
+
222
+ Developed with ❤️ by **vu-tran** for high-performance React Native applications.
@@ -0,0 +1,49 @@
1
+ buildscript {
2
+ ext.kotlin_version = '1.9.22'
3
+ repositories {
4
+ google()
5
+ mavenCentral()
6
+ }
7
+ dependencies {
8
+ classpath "com.android.tools.build:gradle:8.2.1"
9
+ classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
10
+ }
11
+ }
12
+
13
+ apply plugin: 'com.android.library'
14
+ apply plugin: 'kotlin-android'
15
+
16
+ def safeExtGet(prop, fallback) {
17
+ rootProject.ext.has(prop) ? rootProject.ext.get(prop) : fallback
18
+ }
19
+
20
+ android {
21
+ namespace "com.reactnativeliveactivity"
22
+ compileSdkVersion safeExtGet('compileSdkVersion', 34)
23
+
24
+ defaultConfig {
25
+ minSdkVersion safeExtGet('minSdkVersion', 24)
26
+ targetSdkVersion safeExtGet('targetSdkVersion', 34)
27
+ }
28
+
29
+ compileOptions {
30
+ sourceCompatibility JavaVersion.VERSION_17
31
+ targetCompatibility JavaVersion.VERSION_17
32
+ }
33
+
34
+ kotlinOptions {
35
+ jvmTarget = '17'
36
+ }
37
+ }
38
+
39
+ repositories {
40
+ google()
41
+ mavenCentral()
42
+ }
43
+
44
+ dependencies {
45
+ implementation 'com.facebook.react:react-android:+'
46
+ implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
47
+ implementation 'androidx.core:core-ktx:1.12.0'
48
+ }
49
+
@@ -0,0 +1,38 @@
1
+ <manifest xmlns:android="http://schemas.android.com/apk/res/android">
2
+
3
+ <uses-permission android:name="android.permission.INTERNET" />
4
+ <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
5
+ <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
6
+ <uses-permission android:name="android.permission.SCHEDULE_EXACT_ALARM" />
7
+
8
+ <application>
9
+ <!-- Receiver xử lý Live Update, Background API Sync & Interactive Widget Actions -->
10
+ <receiver
11
+ android:name=".LiveActivityReceiver"
12
+ android:exported="false">
13
+ <intent-filter>
14
+ <action android:name="com.reactnativeliveactivity.ACTION_REFRESH" />
15
+ <action android:name="com.reactnativeliveactivity.ACTION_WIDGET_ACTION" />
16
+ <action android:name="com.reactnativeliveactivity.ACTION_WIDGET_SYNC" />
17
+ </intent-filter>
18
+ </receiver>
19
+
20
+ <!-- Service Headless JS chạy tác vụ ngầm khi người dùng bấm nút trên Widget mà App đang đóng -->
21
+ <service
22
+ android:name=".LiveActivityHeadlessTaskService"
23
+ android:exported="false" />
24
+
25
+ <!-- Home Screen AppWidgetProvider tự động tích hợp cho Android -->
26
+ <receiver
27
+ android:name=".DynamicHomeScreenWidgetProvider"
28
+ android:label="Live Widgets"
29
+ android:exported="true">
30
+ <intent-filter>
31
+ <action android:name="android.appwidget.action.APPWIDGET_UPDATE" />
32
+ </intent-filter>
33
+ <meta-data
34
+ android:name="android.appwidget.provider"
35
+ android:resource="@xml/rn_live_widget_info" />
36
+ </receiver>
37
+ </application>
38
+ </manifest>