react-native-live-widgets 0.0.0-stage → 1.1.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 (65) hide show
  1. package/CHANGELOG.md +21 -0
  2. package/LICENSE +21 -0
  3. package/README.md +367 -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 +441 -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/app.plugin.js +114 -0
  19. package/assets/cross_platform_parity.png +0 -0
  20. package/assets/dashboard_features.png +0 -0
  21. package/assets/donate_qr.png +0 -0
  22. package/assets/dynamic_island_expanded.png +0 -0
  23. package/assets/home_widget_interactive.png +0 -0
  24. package/assets/lock_screen_live_activity.png +0 -0
  25. package/cli/setup.js +491 -0
  26. package/docs/EXPO-GUIDE-EN.md +405 -0
  27. package/docs/EXPO-GUIDE-VI.md +427 -0
  28. package/docs/GUIDE-EN.md +847 -0
  29. package/docs/GUIDE-VI.md +845 -0
  30. package/docs/widgets.md +52 -0
  31. package/ios/Bridge/LiveActivityModule.m +105 -0
  32. package/ios/Bridge/LiveActivityModule.swift +957 -0
  33. package/ios/Intents/DynamicWidgetActionIntent.swift +38 -0
  34. package/ios/Models/DynamicActivityAttributes.swift +22 -0
  35. package/ios/Models/DynamicLayoutModels.swift +243 -0
  36. package/ios/Renderer/ColorHexExtension.swift +49 -0
  37. package/ios/Renderer/DynamicNodeRegistry.swift +54 -0
  38. package/ios/Renderer/DynamicNodeView.swift +1060 -0
  39. package/ios/Storage/DynamicWidgetImageCache.swift +137 -0
  40. package/ios/Storage/DynamicWidgetStateStore.swift +162 -0
  41. package/ios/Widgets/DynamicHomeScreenWidget.swift +435 -0
  42. package/ios/Widgets/DynamicLiveActivityWidget.swift +79 -0
  43. package/lib/builder.d.ts +60 -0
  44. package/lib/builder.d.ts.map +1 -0
  45. package/lib/builder.js +292 -0
  46. package/lib/builder.js.map +1 -0
  47. package/lib/dispatcher.d.ts +16 -0
  48. package/lib/dispatcher.d.ts.map +1 -0
  49. package/lib/dispatcher.js +18 -0
  50. package/lib/dispatcher.js.map +1 -0
  51. package/lib/index.d.ts +199 -0
  52. package/lib/index.d.ts.map +1 -0
  53. package/lib/index.js +621 -0
  54. package/lib/index.js.map +1 -0
  55. package/lib/types.d.ts +489 -0
  56. package/lib/types.d.ts.map +1 -0
  57. package/lib/types.js +9 -0
  58. package/lib/types.js.map +1 -0
  59. package/package.json +85 -4
  60. package/react-native-live-widgets.podspec +38 -0
  61. package/src/builder.ts +409 -0
  62. package/src/dispatcher.ts +25 -0
  63. package/src/index.ts +689 -0
  64. package/src/react-native-env.d.ts +29 -0
  65. package/src/types.ts +595 -0
package/CHANGELOG.md ADDED
@@ -0,0 +1,21 @@
1
+ # Changelog
2
+
3
+ All notable changes to `react-native-live-widgets` will be documented in this file.
4
+
5
+ ## [1.1.0] - 2026-11-16
6
+ ### Added
7
+ - **Expo Config Plugin (`app.plugin.js`)**: Full Expo & EAS Build support (`npx expo prebuild` / `npx expo run:ios` / `npx expo run:android`). Automatically configures `NSSupportsLiveActivities` and `NSSupportsLiveActivitiesFrequentUpdates` in iOS `Info.plist`, App Groups entitlements, and Android notifications & foreground service permissions.
8
+
9
+ ### Fixed
10
+ - **TypeScript Module Resolution**: Fixed `error TS7016` when resolving React Native package exports by updating to `moduleResolution: bundler` and `module: ES2020`.
11
+ - **Global `__DEV__` Declaration**: Fixed `error TS2304: Cannot find name '__DEV__'` with safe typing and fallback checks.
12
+
13
+ ## [1.0.0] - 2026-11-15
14
+ ### Added
15
+ - **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`.
16
+ - **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.
17
+ - **Background API Auto-Sync (`Widget.setRemoteConfig`)**: Autonomous background HTTP JSON fetch and `{{field}}` template interpolation even when the main app is force-killed.
18
+ - **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).
19
+ - **Unified Push Token Management**: `devicePushToken`, `pushToStartToken` (iOS 17.2+), and `activityUpdateToken` across iOS APNs and Android FCM.
20
+ - **CLI Setup Wizard**: `npx react-native-live-widgets init` for automatic iOS & Android project configuration.
21
+
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,368 @@
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/npm/v/react-native-live-widgets.svg?style=for-the-badge&logo=npm&color=CB3837)](https://www.npmjs.com/package/react-native-live-widgets)
6
+ [![Expo Ready](https://img.shields.io/badge/Expo-Config%20Plugin-000020.svg?style=for-the-badge&logo=expo)](https://expo.dev)
7
+ [![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)
8
+ [![TypeScript](https://img.shields.io/badge/TypeScript-100%25-3178C6.svg?style=for-the-badge&logo=typescript)](https://www.typescriptlang.org/)
9
+ [![License](https://img.shields.io/badge/License-MIT-green.svg?style=for-the-badge)](LICENSE)
10
+
11
+ **The Ultimate All-in-One Engine for Live Activities, Dynamic Island, and Interactive Home Screen Widgets in React Native & Expo.**
12
+
13
+ *Write 100% Declarative TypeScript. Render dynamically to Native SwiftUI (WidgetKit) & Android 2D Canvas without touching Xcode or Android Studio.*
14
+
15
+ [📖 English Guide](docs/GUIDE-EN.md) • [🇻🇳 Hướng dẫn Tiếng Việt](docs/GUIDE-VI.md) • [⚡ Expo Guide](docs/EXPO-GUIDE-VI.md) • [📱 Bare RN Demo](https://github.com/React-Native-Vu/LiveWidgetsExample) • [⚡ Expo Demo](https://github.com/React-Native-Vu/LiveWidgetsExampleExpo) • [✨ Tính năng](#-key-features) • [⚡ Cài đặt](#-quick-start) • [☕ Ủng hộ tác giả](#-sponsor--donate-ủng-hộ-tác-giả)
16
+
17
+ ---
18
+
19
+ </div>
20
+
21
+ ## 📱 Live Demo Example Apps
22
+
23
+ Full, ready-to-run demo applications are available on GitHub for both architectures:
24
+
25
+ | Platform | Repository | Description |
26
+ | :--- | :--- | :--- |
27
+ | **⚛️ Bare React Native CLI** | 👉 **[React-Native-Vu/LiveWidgetsExample](https://github.com/React-Native-Vu/LiveWidgetsExample)** | Full Xcode Widget Extension & Android Studio setup |
28
+ | **🚀 Expo (SDK 58 / CNG)** | 👉 **[React-Native-Vu/LiveWidgetsExampleExpo](https://github.com/React-Native-Vu/LiveWidgetsExampleExpo)** | Continuous Native Generation via Expo Config Plugin |
29
+
30
+ ### ✨ Highlights of Both Demos:
31
+ - 🚀 **100% Pre-configured**: Xcode App Groups, `WidgetExtension`, and Android `AppWidgetProvider` ready out of the box.
32
+ - 🎨 **5 Real-world Presets**:
33
+ 1. **Executive KPI Dashboard**: Live sales sync, circular progress ring, and weekly chart.
34
+ 2. **Coffee Delivery Tracker**: Dynamic Island countdown and delivery driver status.
35
+ 3. **Interactive Task Checklist**: Check off items right from your Home Screen without opening the app.
36
+ 4. **Music & Audio Player**: Dynamic Island equalizer animation and lock screen media style.
37
+ 5. **Flight Status**: Real-time gate, departure time, and airport progress bar.
38
+ - 🔄 **Bidirectional Real-Time Sync**: Instant state updates between Main App and WidgetKit.
39
+
40
+ #### 1. Clone & Run Bare React Native Demo:
41
+ ```bash
42
+ git clone https://github.com/React-Native-Vu/LiveWidgetsExample.git
43
+ cd LiveWidgetsExample && npm install
44
+ npx react-native run-ios # or npx react-native run-android
45
+ ```
46
+
47
+ #### 2. Clone & Run Expo Demo:
48
+ ```bash
49
+ git clone https://github.com/React-Native-Vu/LiveWidgetsExampleExpo.git
50
+ cd LiveWidgetsExampleExpo && npm install
51
+ npx expo prebuild
52
+ npx expo run:ios # or npx expo run:android
53
+ ```
54
+
55
+ ---
56
+
57
+ ## 📸 Showcase & Demos
58
+
59
+ <div align="center">
60
+ <table>
61
+ <tr>
62
+ <td width="50%" align="center">
63
+ <b>🏝️ Dynamic Island Expanded & KPI Dashboard</b><br/><br/>
64
+ <img src="assets/dynamic_island_expanded.png" alt="Dynamic Island Expanded" width="380" />
65
+ </td>
66
+ <td width="50%" align="center">
67
+ <b>📱 Interactive Home Screen Widget (iOS)</b><br/><br/>
68
+ <img src="assets/home_widget_interactive.png" alt="Home Screen Widget Interactive" width="380" />
69
+ </td>
70
+ </tr>
71
+ <tr>
72
+ <td width="50%" align="center">
73
+ <b>🔒 Lock Screen Live Activity & Gauges</b><br/><br/>
74
+ <img src="assets/lock_screen_live_activity.png" alt="Lock Screen Live Activity" width="380" />
75
+ </td>
76
+ <td width="50%" align="center">
77
+ <b>🤖 100% Feature Parity (Android & iOS)</b><br/><br/>
78
+ <img src="assets/cross_platform_parity.png" alt="Cross Platform Parity" width="380" />
79
+ </td>
80
+ </tr>
81
+ </table>
82
+ </div>
83
+
84
+ ---
85
+
86
+ ## 💡 Why `react-native-live-widgets`?
87
+
88
+ 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.
89
+
90
+ `react-native-live-widgets` solves this with a **Declarative TypeScript UI DSL**:
91
+ - 🚫 **No SwiftUI / Kotlin coding required** for custom screens.
92
+ - 🎨 **100% Declarative UI in React Native (`UI.VStack`, `UI.HStack`, `UI.Text`, `UI.Button`, `UI.Progress`, `UI.Image`)**.
93
+ - 🚀 **Full Expo & EAS Build Support** via automated Expo Config Plugin (`app.plugin.js`).
94
+ - ⚡ **Interactive Buttons**: Tap buttons on the Home Screen Widget to run native Swift extensions or wake up TypeScript handlers.
95
+ - 🔄 **Realtime Data Sync (`SharedStorage`)**: Single source of truth across Main App, Lock Screen, and Home Screen.
96
+ - 🌐 **Silent Background Remote API Sync**: Automatically fetch REST APIs and update Widgets even when the App is **Force-Killed**.
97
+ - 🤖 **Android Parity**: Supports Android 16+ Promoted Live Notifications and Home Screen AppWidgets.
98
+
99
+ ---
100
+
101
+ ## ✨ Key Features
102
+
103
+ ### 1. 🏝️ Dynamic Island & Lock Screen Live Activities (iOS 16.1+)
104
+ - **All Dynamic Island Modes**: `compactLeading`, `compactTrailing`, `minimal`, and `expanded`.
105
+ - **Realtime Timers & Progress**: Countdown timers, segmented progress bars, and battery/progress rings with zero battery drain.
106
+ - **Smart Dismissal Policies**: `immediate`, `afterDate`, or `default`.
107
+
108
+ ### 2. 📱 Interactive Home Screen Widgets (iOS WidgetKit & Android AppWidget)
109
+ - Supports **Small**, **Medium**, and **Large** widget families.
110
+ - **Multi-page & Tabs**: Switch tabs or carousel pages directly on the widget (`actionId: "page:next"`).
111
+ - **Checklist & Toggles**: Toggle checkboxes and switch states without opening the app (`actionId: "toggle:<key>"`).
112
+ - **Dark & Light Mode**: Declarative color tokens `{ light: '#FFF', dark: '#0F172A' }`.
113
+
114
+ ### 3. ⚡ Bi-directional Action Dispatcher (TypeScript + Native)
115
+ - Tap a widget button outside on the Home Screen to trigger a registered TypeScript function:
116
+ ```ts
117
+ LiveActivity.registerAction('action_checkin', async (payload) => {
118
+ // Runs inside React Native JS engine!
119
+ console.log('Action triggered from Home Screen Widget:', payload);
120
+ });
121
+ ```
122
+ - **App-Killed Protection**: Native fallback ensures UI responds instantly and persists data even if the main app is terminated.
123
+
124
+ ### 4. 🌐 Background Remote API Sync (Zero Code Backend)
125
+ - Configure an API endpoint with `Widget.setRemoteConfig`:
126
+ ```ts
127
+ await Widget.setRemoteConfig('main', {
128
+ url: 'https://api.yourcompany.com/v1/shifts/current',
129
+ method: 'GET',
130
+ refreshIntervalMinutes: 15
131
+ }, APP_GROUP);
132
+ ```
133
+ - The native Extension fetches fresh JSON and dynamically replaces `{{variables}}` in your widget layout in the background.
134
+
135
+ ### 5. 🔔 APNs & FCM Token Management
136
+ - One-call retrieval for all push tokens:
137
+ ```ts
138
+ const tokens = await LiveActivity.getAllPushTokens();
139
+ // tokens.devicePushToken
140
+ // tokens.pushToStartToken (iOS 17.2+)
141
+ // tokens.activityUpdateToken
142
+ ```
143
+
144
+ ---
145
+
146
+ ## ⚡ Quick Start
147
+
148
+ ### 1. Installation
149
+
150
+ ```bash
151
+ # React Native CLI
152
+ npm install react-native-live-widgets
153
+
154
+ # Expo (Managed or Bare)
155
+ npx expo install react-native-live-widgets
156
+ ```
157
+
158
+ ---
159
+
160
+ ### 2. Configuration
161
+
162
+ #### A. If using Expo (Config Plugin)
163
+
164
+ Add `react-native-live-widgets` to your `app.json` or `app.config.js`:
165
+
166
+ ```json
167
+ {
168
+ "expo": {
169
+ "name": "My Expo App",
170
+ "plugins": [
171
+ [
172
+ "react-native-live-widgets",
173
+ {
174
+ "appGroup": "group.com.yourcompany.app",
175
+ "enableLiveActivities": true,
176
+ "frequentUpdates": true
177
+ }
178
+ ]
179
+ ]
180
+ }
181
+ }
182
+ ```
183
+
184
+ Then generate native projects or run with Expo Dev Client:
185
+
186
+ ```bash
187
+ # 1. Generate native folders
188
+ npx expo prebuild
189
+
190
+ # 2. Automatically scaffold & link Xcode Widget Extension target
191
+ npx react-native-live-widgets init --group group.com.yourcompany.app
192
+
193
+ # 3. Run on iOS Simulator & Android Emulator:
194
+ npx expo run:ios
195
+ npx expo run:android
196
+ ```
197
+
198
+ > 📖 **Detailed Step-by-Step Expo Guide**: [English](docs/EXPO-GUIDE-EN.md) • [Tiếng Việt](docs/EXPO-GUIDE-VI.md)
199
+
200
+ #### B. If using Bare React Native CLI
201
+
202
+ Run the automated scaffolding script in your React Native project root:
203
+
204
+ ```bash
205
+ npx react-native-live-widgets init --group group.com.yourcompany.app
206
+ ```
207
+
208
+ This will automatically:
209
+ - Inject `NSSupportsLiveActivities` and `NSSupportsLiveActivitiesFrequentUpdates` into `Info.plist`.
210
+ - Scaffold the `LiveWidgetsExtension` bundle in your `ios/` folder.
211
+ - Configure `AndroidManifest.xml` with required notification permissions.
212
+
213
+ And install CocoaPods dependencies:
214
+
215
+ ```bash
216
+ cd ios && pod install
217
+ ```
218
+
219
+ ---
220
+
221
+ ## 💻 Code Example
222
+
223
+ ### 1. Start a Live Activity with Dynamic Island
224
+
225
+ ```tsx
226
+ import { UI, LiveActivity } from 'react-native-live-widgets';
227
+
228
+ await LiveActivity.start({
229
+ activityId: 'kpi_q4_2026',
230
+ dynamicIsland: {
231
+ compactLeading: UI.Text('KPI Q4', { color: '#38BDF8', fontWeight: 'bold' }),
232
+ compactTrailing: UI.Text('86%', { color: '#10B981', fontWeight: 'bold' }),
233
+ minimal: UI.Text('86%', { color: '#10B981' }),
234
+ expanded: UI.VStack(
235
+ { padding: 14, spacing: 8, backgroundColor: '#0F172A' },
236
+ UI.HStack(
237
+ { justifyContent: 'spaceBetween' },
238
+ UI.Text('BẢNG ĐIỀU HÀNH KPI', { fontSize: 11, color: '#94A3B8' }),
239
+ UI.Badge({ text: '86% Hoàn thành', backgroundColor: '#064E3B', textColor: '#6EE7B7' })
240
+ ),
241
+ UI.Text('Mục tiêu Q4/2026', { fontSize: 16, fontWeight: 'bold', color: '#FFFFFF' }),
242
+ UI.Progress({
243
+ style: 'bar',
244
+ value: 0.86,
245
+ tintColor: '#10B981',
246
+ trackColor: '#334155'
247
+ }),
248
+ UI.Text('Doanh số 12.8 tỷ / 15 tỷ VNĐ • Tăng trưởng +22%', { fontSize: 12, color: '#94A3B8' })
249
+ )
250
+ },
251
+ lockScreen: UI.VStack(
252
+ { padding: 16, backgroundColor: '#0F172A', cornerRadius: 16 },
253
+ UI.HStack(
254
+ { justifyContent: 'spaceBetween' },
255
+ UI.Text('KPI Quý 4: Đạt 86% mục tiêu', { fontSize: 14, fontWeight: 'bold', color: '#FFFFFF' }),
256
+ UI.Badge({ text: '+18%', backgroundColor: '#064E3B', textColor: '#6EE7B7' })
257
+ ),
258
+ UI.Progress({
259
+ style: 'segmented',
260
+ segments: 7,
261
+ currentSegment: 6,
262
+ tintColor: '#38BDF8',
263
+ trackColor: '#1E293B'
264
+ })
265
+ )
266
+ });
267
+ ```
268
+
269
+ ### 2. Configure Home Screen Widget with Live Sync
270
+
271
+ ```tsx
272
+ import { UI, Widget, SharedStorage } from 'react-native-live-widgets';
273
+
274
+ const APP_GROUP = 'group.com.yourcompany.app';
275
+
276
+ // Set shared data
277
+ await SharedStorage.set('kpi_percent', '86', APP_GROUP);
278
+ await SharedStorage.set('revenue_month', '4.85 Tỷ đ', APP_GROUP);
279
+
280
+ // Build Declarative Layout
281
+ await Widget.setLayout('main', {
282
+ large: UI.VStack(
283
+ { padding: 16, backgroundColor: '#0B132B', cornerRadius: 20 },
284
+ UI.HStack(
285
+ { justifyContent: 'spaceBetween' },
286
+ UI.Text('TỔNG QUAN ĐIỀU HÀNH (KPI & BIỂU ĐỒ)', { fontSize: 11, color: '#38BDF8', fontWeight: 'bold' }),
287
+ UI.Badge({ text: 'LIVE SYNC', backgroundColor: '#064E3B', textColor: '#6EE7B7' })
288
+ ),
289
+ UI.HStack(
290
+ { spacing: 12, marginTop: 10 },
291
+ UI.VStack(
292
+ { width: 90, alignItems: 'center' },
293
+ UI.Progress({ style: 'circular', value: 0.86, tintColor: '#38BDF8', trackColor: '#1E293B' }),
294
+ UI.Text('86%', { fontSize: 16, fontWeight: 'bold', color: '#FFFFFF' }),
295
+ UI.Text('KPI Quý', { fontSize: 10, color: '#94A3B8' })
296
+ )
297
+ ),
298
+ UI.Spacer(),
299
+ UI.Button('Duyệt báo cáo doanh thu tuần', {
300
+ actionId: 'action_approve_report',
301
+ backgroundColor: '#1E293B',
302
+ textColor: '#FFFFFF'
303
+ })
304
+ )
305
+ }, APP_GROUP);
306
+
307
+ await Widget.reloadAll();
308
+ ```
309
+
310
+ ---
311
+
312
+ ## 📊 Platform Feature Parity Matrix
313
+
314
+ | Feature | iOS 16.1+ | Android (API 24 - 36) |
315
+ | :--- | :---: | :---: |
316
+ | **Declarative UI Engine (`UI.*`)** | SwiftUI dynamic tree | High-DPI Canvas 2D Bitmap |
317
+ | **Dynamic Island (All 4 layouts)** | ✅ Supported | 🔄 Mapped to Promoted Ongoing (Android 16+) |
318
+ | **Lock Screen Live Activity** | ✅ Supported | ✅ Ongoing Rich Notification |
319
+ | **Home Screen Widgets** | Small, Medium, Large | Resizable Grid AppWidgets |
320
+ | **Interactive Buttons** | iOS 17+ AppIntents | RemoteViews PendingIntent |
321
+ | **SharedStorage Data Sync** | App Group UserDefaults | Context SharedPreferences |
322
+ | **Remote API Silent Sync** | Background Timeline URLSession | WorkManager / Background Fetch |
323
+ | **Push Remote Updates** | Apple APNs Activity Tokens | Firebase Cloud Messaging (FCM) |
324
+ | **Expo & EAS Build Ready** | ✅ Automated Config Plugin | ✅ Automated Config Plugin |
325
+
326
+ ---
327
+
328
+ ## ☕ Sponsor & Donate (Ủng hộ tác giả)
329
+
330
+ `react-native-live-widgets` là dự án mã nguồn mở **hoàn toàn miễn phí (100% Free & MIT License)**, được phát triển và duy trì với tâm huyết mang lại giải pháp Live Activities & Widgets tốt nhất cho cộng đồng React Native Việt Nam và quốc tế.
331
+
332
+ Nếu thư viện này giúp ích cho dự án hoặc công ty của bạn, bạn có thể **mời tác giả một tách cà phê** để tiếp thêm động lực phát triển thêm nhiều tính năng mới nhé! ☕❤️
333
+
334
+ <div align="center">
335
+
336
+ <img src="assets/donate_qr.png" alt="Donate qua VietQR VPBank" width="300" style="border-radius: 16px; box-shadow: 0 4px 20px rgba(0,0,0,0.15);" />
337
+
338
+ ### 🏦 Thông tin chuyển khoản ủng hộ:
339
+ - **Ngân hàng**: VPBank (Ngân hàng TMCP Việt Nam Thịnh Vượng)
340
+ - **Số tài khoản / Số điện thoại**: `0906472426`
341
+ - **Chủ tài khoản**: `TRAN LE VU`
342
+ - **Nội dung**: `LiveWidgets Support` hoặc lời nhắn của bạn
343
+
344
+ *Chân thành cảm ơn sự đồng hành và ủng hộ quý báu của bạn!* 🙏✨
345
+
346
+ </div>
347
+
348
+ ---
349
+
350
+ ## 📚 Documentation & Guides
351
+
352
+ - 📱 **[LiveWidgetsExample Demo Project](https://github.com/React-Native-Vu/LiveWidgetsExample)**: Complete working sample app demonstrating all 5 presets with bidirectional sync on iOS & Android.
353
+ - 🇬🇧 **[Full English Developer Guide](docs/GUIDE-EN.md)**: Architecture, DSL specs, push notification server configuration, and best practices.
354
+ - 🇻🇳 **[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.
355
+
356
+ ---
357
+
358
+ ## 🤝 Contributing
359
+
360
+ Contributions are welcome! Please feel free to submit a Pull Request or open an Issue on [GitHub Repository](https://github.com/React-Native-Vu/react-native-live-widgets).
361
+
362
+ ---
363
+
364
+ ## 📄 License
365
+
366
+ Distributed under the **MIT License**. See [LICENSE](LICENSE) for more information.
367
+
368
+ Developed with ❤️ by **vu-tran** for high-performance React Native & Expo 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>