react-native-live-widgets 1.1.0 → 1.1.1
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.
- package/CHANGELOG.md +6 -0
- package/README.md +3 -1
- package/android/build.gradle +14 -20
- package/android/src/main/AndroidManifest.xml +1 -0
- package/android/src/main/java/com/reactnativeliveactivity/liveactivity/LiveActivityHeadlessTaskService.kt +8 -0
- package/android/src/main/java/com/reactnativeliveactivity/liveactivity/LiveActivityReceiver.kt +4 -1
- package/android/src/main/java/com/reactnativeliveactivity/renderer/DynamicWidgetCanvasRenderer.kt +29 -3
- package/android/src/main/java/com/reactnativeliveactivity/storage/DynamicWidgetStateStore.kt +21 -0
- package/android/src/main/java/com/reactnativeliveactivity/widgets/DynamicHomeScreenWidgetProvider.kt +51 -15
- package/android/src/main/res/layout/rn_live_widget_host.xml +64 -74
- package/docs/GUIDE-EN.md +18 -0
- package/docs/GUIDE-VI.md +18 -0
- package/docs/index.html +405 -0
- package/docs/llms-full.txt +118 -0
- package/docs/llms.txt +66 -0
- package/package.json +2 -1
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,12 @@
|
|
|
2
2
|
|
|
3
3
|
All notable changes to `react-native-live-widgets` will be documented in this file.
|
|
4
4
|
|
|
5
|
+
## [1.1.1] - 2026-11-16
|
|
6
|
+
### Fixed
|
|
7
|
+
- **Android Widget Interaction Crash**: Added `android.permission.WAKE_LOCK` and safely wrapped `HeadlessJsTaskService` wake lock acquisition to prevent `SecurityException` on widget tap events.
|
|
8
|
+
- **Android Hit Zone Accuracy**: Upgraded `rn_live_widget_host.xml` to a dynamic 6-row x 3-column interaction grid (`rn_hit_r0_c0` - `rn_hit_r5_c2`), mapping button physical coordinates (`yFraction`, `xFraction`) accurately to fix misaligned tap zones.
|
|
9
|
+
- **Background Headless Responsiveness**: Added native state store handling and `LiveActivity.registerBackgroundActionHandler()` support for zero-latency widget interactions even when the app is swiped away or force-killed.
|
|
10
|
+
|
|
5
11
|
## [1.1.0] - 2026-11-16
|
|
6
12
|
### Added
|
|
7
13
|
- **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.
|
package/README.md
CHANGED
|
@@ -4,6 +4,8 @@
|
|
|
4
4
|
|
|
5
5
|
[](https://www.npmjs.com/package/react-native-live-widgets)
|
|
6
6
|
[](https://expo.dev)
|
|
7
|
+
[](https://react-native-vu.github.io/react-native-live-widgets/)
|
|
8
|
+
[](https://react-native-vu.github.io/react-native-live-widgets/llms.txt)
|
|
7
9
|
[](https://github.com/React-Native-Vu/react-native-live-widgets)
|
|
8
10
|
[](https://www.typescriptlang.org/)
|
|
9
11
|
[](LICENSE)
|
|
@@ -12,7 +14,7 @@
|
|
|
12
14
|
|
|
13
15
|
*Write 100% Declarative TypeScript. Render dynamically to Native SwiftUI (WidgetKit) & Android 2D Canvas without touching Xcode or Android Studio.*
|
|
14
16
|
|
|
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)
|
|
17
|
+
[🌐 Docs Website](https://react-native-vu.github.io/react-native-live-widgets/) • [🤖 llms.txt](https://react-native-vu.github.io/react-native-live-widgets/llms.txt) • [🧠 AI Agent Skill](skills/react-native-live-widgets/SKILL.md) • [📖 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)
|
|
16
18
|
|
|
17
19
|
---
|
|
18
20
|
|
package/android/build.gradle
CHANGED
|
@@ -1,29 +1,17 @@
|
|
|
1
|
-
|
|
2
|
-
ext.
|
|
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
|
-
}
|
|
1
|
+
def safeExtGet(prop, fallback) {
|
|
2
|
+
rootProject.ext.has(prop) ? rootProject.ext.get(prop) : fallback
|
|
11
3
|
}
|
|
12
4
|
|
|
13
5
|
apply plugin: 'com.android.library'
|
|
14
6
|
apply plugin: 'kotlin-android'
|
|
15
7
|
|
|
16
|
-
def safeExtGet(prop, fallback) {
|
|
17
|
-
rootProject.ext.has(prop) ? rootProject.ext.get(prop) : fallback
|
|
18
|
-
}
|
|
19
|
-
|
|
20
8
|
android {
|
|
21
9
|
namespace "com.reactnativeliveactivity"
|
|
22
|
-
compileSdkVersion safeExtGet('compileSdkVersion',
|
|
10
|
+
compileSdkVersion safeExtGet('compileSdkVersion', safeExtGet('compileSdk', 35))
|
|
23
11
|
|
|
24
12
|
defaultConfig {
|
|
25
|
-
minSdkVersion safeExtGet('minSdkVersion', 24)
|
|
26
|
-
targetSdkVersion safeExtGet('targetSdkVersion',
|
|
13
|
+
minSdkVersion safeExtGet('minSdkVersion', safeExtGet('minSdk', 24))
|
|
14
|
+
targetSdkVersion safeExtGet('targetSdkVersion', safeExtGet('targetSdk', 35))
|
|
27
15
|
}
|
|
28
16
|
|
|
29
17
|
compileOptions {
|
|
@@ -42,8 +30,14 @@ repositories {
|
|
|
42
30
|
}
|
|
43
31
|
|
|
44
32
|
dependencies {
|
|
45
|
-
|
|
46
|
-
|
|
33
|
+
// Resolve react-android safely according to consumer project
|
|
34
|
+
if (findProject(':ReactAndroid') != null) {
|
|
35
|
+
implementation project(':ReactAndroid')
|
|
36
|
+
} else {
|
|
37
|
+
implementation 'com.facebook.react:react-android'
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
def kotlinVersion = safeExtGet('kotlinVersion', safeExtGet('kotlin_version', '2.1.20'))
|
|
41
|
+
implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlinVersion"
|
|
47
42
|
implementation 'androidx.core:core-ktx:1.12.0'
|
|
48
43
|
}
|
|
49
|
-
|
|
@@ -4,6 +4,7 @@
|
|
|
4
4
|
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
|
|
5
5
|
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
|
|
6
6
|
<uses-permission android:name="android.permission.SCHEDULE_EXACT_ALARM" />
|
|
7
|
+
<uses-permission android:name="android.permission.WAKE_LOCK" />
|
|
7
8
|
|
|
8
9
|
<application>
|
|
9
10
|
<!-- Receiver xử lý Live Update, Background API Sync & Interactive Widget Actions -->
|
|
@@ -6,6 +6,14 @@ import com.facebook.react.bridge.Arguments
|
|
|
6
6
|
import com.facebook.react.jstasks.HeadlessJsTaskConfig
|
|
7
7
|
|
|
8
8
|
class LiveActivityHeadlessTaskService : HeadlessJsTaskService() {
|
|
9
|
+
override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int {
|
|
10
|
+
return try {
|
|
11
|
+
super.onStartCommand(intent, flags, startId)
|
|
12
|
+
} catch (_: Throwable) {
|
|
13
|
+
START_NOT_STICKY
|
|
14
|
+
}
|
|
15
|
+
}
|
|
16
|
+
|
|
9
17
|
override fun getTaskConfig(intent: Intent?): HeadlessJsTaskConfig? {
|
|
10
18
|
val actionId = intent?.getStringExtra("actionId") ?: return null
|
|
11
19
|
val activityId = intent.getStringExtra("activityId") ?: ""
|
package/android/src/main/java/com/reactnativeliveactivity/liveactivity/LiveActivityReceiver.kt
CHANGED
|
@@ -55,8 +55,11 @@ class LiveActivityReceiver : BroadcastReceiver() {
|
|
|
55
55
|
putExtra("actionId", actionId)
|
|
56
56
|
putExtra("activityId", activityId)
|
|
57
57
|
}
|
|
58
|
+
try {
|
|
59
|
+
com.facebook.react.HeadlessJsTaskService.acquireWakeLockNow(context)
|
|
60
|
+
} catch (_: Throwable) {}
|
|
58
61
|
context.startService(headlessIntent)
|
|
59
|
-
} catch (_:
|
|
62
|
+
} catch (_: Throwable) {}
|
|
60
63
|
} finally {
|
|
61
64
|
pendingResult.finish()
|
|
62
65
|
}
|
package/android/src/main/java/com/reactnativeliveactivity/renderer/DynamicWidgetCanvasRenderer.kt
CHANGED
|
@@ -21,7 +21,10 @@ import kotlin.math.roundToInt
|
|
|
21
21
|
data class ButtonActionBinding(
|
|
22
22
|
val actionId: String,
|
|
23
23
|
val deepLink: String?,
|
|
24
|
-
val zone: String // "top", "mid", "bot"
|
|
24
|
+
val zone: String = "mid", // "top", "mid", "bot"
|
|
25
|
+
val xFraction: Float = 0.5f,
|
|
26
|
+
val yFraction: Float = 0.5f,
|
|
27
|
+
val widthFraction: Float = 1.0f
|
|
25
28
|
)
|
|
26
29
|
|
|
27
30
|
object DynamicWidgetCanvasRenderer {
|
|
@@ -576,7 +579,19 @@ object DynamicWidgetCanvasRenderer {
|
|
|
576
579
|
top > totalHeight * 0.76f -> "bot"
|
|
577
580
|
else -> "mid"
|
|
578
581
|
}
|
|
579
|
-
|
|
582
|
+
val xF = ((left + btnW / 2f) / availWidth).coerceIn(0f, 1f)
|
|
583
|
+
val yF = ((top + btnH / 2f) / totalHeight).coerceIn(0f, 1f)
|
|
584
|
+
val wF = (btnW / availWidth).coerceIn(0.1f, 1f)
|
|
585
|
+
bindings.add(
|
|
586
|
+
ButtonActionBinding(
|
|
587
|
+
actionId = actionId,
|
|
588
|
+
deepLink = deepLink,
|
|
589
|
+
zone = zone,
|
|
590
|
+
xFraction = xF,
|
|
591
|
+
yFraction = yF,
|
|
592
|
+
widthFraction = if (fullWidth) 1.0f else wF
|
|
593
|
+
)
|
|
594
|
+
)
|
|
580
595
|
}
|
|
581
596
|
btnH + 1.5f * density
|
|
582
597
|
}
|
|
@@ -912,7 +927,18 @@ object DynamicWidgetCanvasRenderer {
|
|
|
912
927
|
top > totalHeight * 0.76f -> "bot"
|
|
913
928
|
else -> "mid"
|
|
914
929
|
}
|
|
915
|
-
|
|
930
|
+
val xF = ((left + availWidth / 2f) / availWidth).coerceIn(0f, 1f)
|
|
931
|
+
val yF = ((top + usedH / 2f) / totalHeight).coerceIn(0f, 1f)
|
|
932
|
+
bindings.add(
|
|
933
|
+
ButtonActionBinding(
|
|
934
|
+
actionId = actionId,
|
|
935
|
+
deepLink = deepLink,
|
|
936
|
+
zone = zone,
|
|
937
|
+
xFraction = xF,
|
|
938
|
+
yFraction = yF,
|
|
939
|
+
widthFraction = 1.0f
|
|
940
|
+
)
|
|
941
|
+
)
|
|
916
942
|
}
|
|
917
943
|
usedH
|
|
918
944
|
}
|
package/android/src/main/java/com/reactnativeliveactivity/storage/DynamicWidgetStateStore.kt
CHANGED
|
@@ -161,6 +161,20 @@ object DynamicWidgetStateStore {
|
|
|
161
161
|
val current = state.toggledItems[key] ?: false
|
|
162
162
|
state.toggledItems[key] = !current
|
|
163
163
|
}
|
|
164
|
+
actionId == "action_counter_inc" || actionId.startsWith("counter:inc") -> {
|
|
165
|
+
val current = (readSharedString(context, "widget_counter_value")?.toIntOrNull() ?: 10) + 1
|
|
166
|
+
writeSharedString(context, "widget_counter_value", current.toString())
|
|
167
|
+
state.remoteVariables["counter"] = current.toString()
|
|
168
|
+
}
|
|
169
|
+
actionId == "action_counter_dec" || actionId.startsWith("counter:dec") -> {
|
|
170
|
+
val current = (readSharedString(context, "widget_counter_value")?.toIntOrNull() ?: 10) - 1
|
|
171
|
+
writeSharedString(context, "widget_counter_value", current.toString())
|
|
172
|
+
state.remoteVariables["counter"] = current.toString()
|
|
173
|
+
}
|
|
174
|
+
actionId == "action_counter_reset" || actionId.startsWith("counter:reset") -> {
|
|
175
|
+
writeSharedString(context, "widget_counter_value", "0")
|
|
176
|
+
state.remoteVariables["counter"] = "0"
|
|
177
|
+
}
|
|
164
178
|
}
|
|
165
179
|
|
|
166
180
|
saveState(context, state)
|
|
@@ -177,6 +191,13 @@ object DynamicWidgetStateStore {
|
|
|
177
191
|
?: SimpleDateFormat("HH:mm:ss", Locale.getDefault()).format(Date())
|
|
178
192
|
raw = raw.replace("{{_lastSyncTime}}", syncTime)
|
|
179
193
|
|
|
194
|
+
val counterVal = readSharedString(context, "widget_counter_value")
|
|
195
|
+
if (counterVal != null) {
|
|
196
|
+
raw = raw.replace(Regex("\"text\":\"-?\\d+\",\"props\":\\{\"fontSize\":(26|32)"), "\"text\":\"$counterVal\",\"props\":{\"fontSize\":$1")
|
|
197
|
+
raw = raw.replace(Regex("\"text\":\"-?\\d+ lượt\","), "\"text\":\"$counterVal lượt\",")
|
|
198
|
+
raw = raw.replace("{{counter}}", counterVal)
|
|
199
|
+
}
|
|
200
|
+
|
|
180
201
|
for ((k, v) in state.remoteVariables) {
|
|
181
202
|
val escaped = v.replace("\"", "\\\"")
|
|
182
203
|
raw = raw.replace("{{$k}}", escaped)
|
package/android/src/main/java/com/reactnativeliveactivity/widgets/DynamicHomeScreenWidgetProvider.kt
CHANGED
|
@@ -13,6 +13,7 @@ import android.util.SizeF
|
|
|
13
13
|
import android.widget.RemoteViews
|
|
14
14
|
import org.json.JSONObject
|
|
15
15
|
import kotlin.math.max
|
|
16
|
+
import kotlin.math.min
|
|
16
17
|
import kotlin.math.roundToInt
|
|
17
18
|
|
|
18
19
|
class DynamicHomeScreenWidgetProvider : AppWidgetProvider() {
|
|
@@ -163,25 +164,60 @@ class DynamicHomeScreenWidgetProvider : AppWidgetProvider() {
|
|
|
163
164
|
appWidgetId: Int,
|
|
164
165
|
bindings: List<ButtonActionBinding>
|
|
165
166
|
) {
|
|
166
|
-
val
|
|
167
|
-
|
|
168
|
-
|
|
167
|
+
val gridIds = listOf(
|
|
168
|
+
listOf(R.id.rn_hit_r0_c0, R.id.rn_hit_r0_c1, R.id.rn_hit_r0_c2, R.id.rn_hit_r0_c3),
|
|
169
|
+
listOf(R.id.rn_hit_r1_c0, R.id.rn_hit_r1_c1, R.id.rn_hit_r1_c2),
|
|
170
|
+
listOf(R.id.rn_hit_r2_c0, R.id.rn_hit_r2_c1, R.id.rn_hit_r2_c2),
|
|
171
|
+
listOf(R.id.rn_hit_r3_c0, R.id.rn_hit_r3_c1, R.id.rn_hit_r3_c2),
|
|
172
|
+
listOf(R.id.rn_hit_r4_c0, R.id.rn_hit_r4_c1, R.id.rn_hit_r4_c2),
|
|
173
|
+
listOf(R.id.rn_hit_r5_c0, R.id.rn_hit_r5_c1, R.id.rn_hit_r5_c2)
|
|
174
|
+
)
|
|
175
|
+
|
|
176
|
+
val cellBindings = mutableMapOf<Int, ButtonActionBinding>()
|
|
169
177
|
|
|
170
|
-
val
|
|
171
|
-
val
|
|
172
|
-
val botBindings = bindings.filter { it.zone == "bot" }
|
|
178
|
+
val topButtons = bindings.filter { it.zone == "top" || it.yFraction < 0.20f }
|
|
179
|
+
val otherButtons = bindings.filter { it !in topButtons }
|
|
173
180
|
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
181
|
+
val row0 = gridIds[0]
|
|
182
|
+
for (c in 0 until min(row0.size, topButtons.size)) {
|
|
183
|
+
cellBindings[row0[c]] = topButtons[c]
|
|
177
184
|
}
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
185
|
+
|
|
186
|
+
for (b in otherButtons) {
|
|
187
|
+
val row = when {
|
|
188
|
+
b.yFraction < 0.35f -> 1
|
|
189
|
+
b.yFraction < 0.52f -> 2
|
|
190
|
+
b.yFraction < 0.62f -> 3
|
|
191
|
+
b.yFraction < 0.75f -> 4
|
|
192
|
+
else -> 5
|
|
193
|
+
}
|
|
194
|
+
|
|
195
|
+
val rowCols = gridIds[row]
|
|
196
|
+
if (b.widthFraction > 0.50f) {
|
|
197
|
+
for (viewId in rowCols) {
|
|
198
|
+
cellBindings[viewId] = b
|
|
199
|
+
}
|
|
200
|
+
} else {
|
|
201
|
+
if (b.xFraction < 0.40f) {
|
|
202
|
+
cellBindings[rowCols[0]] = b
|
|
203
|
+
cellBindings[rowCols[1]] = b
|
|
204
|
+
} else {
|
|
205
|
+
cellBindings[rowCols[1]] = b
|
|
206
|
+
cellBindings[rowCols[2]] = b
|
|
207
|
+
}
|
|
208
|
+
}
|
|
181
209
|
}
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
210
|
+
|
|
211
|
+
var requestIdx = 0
|
|
212
|
+
for (r in gridIds.indices) {
|
|
213
|
+
for (c in gridIds[r].indices) {
|
|
214
|
+
val viewId = gridIds[r][c]
|
|
215
|
+
val b = cellBindings[viewId]
|
|
216
|
+
views.setOnClickPendingIntent(
|
|
217
|
+
viewId,
|
|
218
|
+
createPendingIntent(context, appWidgetId * 100 + requestIdx++, b)
|
|
219
|
+
)
|
|
220
|
+
}
|
|
185
221
|
}
|
|
186
222
|
}
|
|
187
223
|
|
|
@@ -12,101 +12,91 @@
|
|
|
12
12
|
android:scaleType="fitCenter"
|
|
13
13
|
android:contentDescription="Live Widget Content" />
|
|
14
14
|
|
|
15
|
-
<!-- Lớp vùng bấm tương tác (Interactive Hit Zones) cho
|
|
15
|
+
<!-- Lớp vùng bấm tương tác (Interactive Hit Zones: 6 Hàng x 3 Cột) cho mọi layout Widget -->
|
|
16
16
|
<LinearLayout
|
|
17
|
+
android:id="@+id/rn_widget_grid_container"
|
|
17
18
|
android:layout_width="match_parent"
|
|
18
19
|
android:layout_height="match_parent"
|
|
19
20
|
android:orientation="vertical"
|
|
20
|
-
android:weightSum="
|
|
21
|
+
android:weightSum="6">
|
|
21
22
|
|
|
22
|
-
<!--
|
|
23
|
+
<!-- Row 0 (0% - 16.7%) -->
|
|
23
24
|
<LinearLayout
|
|
24
|
-
android:id="@+id/
|
|
25
|
+
android:id="@+id/rn_grid_row_0"
|
|
25
26
|
android:layout_width="match_parent"
|
|
26
27
|
android:layout_height="0dp"
|
|
27
|
-
android:layout_weight="
|
|
28
|
-
android:orientation="horizontal"
|
|
29
|
-
|
|
30
|
-
<TextView
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
android:layout_weight="1"
|
|
35
|
-
android:background="@android:color/transparent" />
|
|
36
|
-
|
|
37
|
-
<TextView
|
|
38
|
-
android:id="@+id/rn_hit_top_2"
|
|
39
|
-
android:layout_width="0dp"
|
|
40
|
-
android:layout_height="match_parent"
|
|
41
|
-
android:layout_weight="1"
|
|
42
|
-
android:background="@android:color/transparent" />
|
|
43
|
-
|
|
44
|
-
<TextView
|
|
45
|
-
android:id="@+id/rn_hit_top_3"
|
|
46
|
-
android:layout_width="0dp"
|
|
47
|
-
android:layout_height="match_parent"
|
|
48
|
-
android:layout_weight="1"
|
|
49
|
-
android:background="@android:color/transparent" />
|
|
50
|
-
|
|
51
|
-
<TextView
|
|
52
|
-
android:id="@+id/rn_hit_top_4"
|
|
53
|
-
android:layout_width="0dp"
|
|
54
|
-
android:layout_height="match_parent"
|
|
55
|
-
android:layout_weight="1"
|
|
56
|
-
android:background="@android:color/transparent" />
|
|
28
|
+
android:layout_weight="1"
|
|
29
|
+
android:orientation="horizontal"
|
|
30
|
+
android:weightSum="4">
|
|
31
|
+
<TextView android:id="@+id/rn_hit_r0_c0" android:layout_width="0dp" android:layout_height="match_parent" android:layout_weight="1" android:background="@android:color/transparent" />
|
|
32
|
+
<TextView android:id="@+id/rn_hit_r0_c1" android:layout_width="0dp" android:layout_height="match_parent" android:layout_weight="1" android:background="@android:color/transparent" />
|
|
33
|
+
<TextView android:id="@+id/rn_hit_r0_c2" android:layout_width="0dp" android:layout_height="match_parent" android:layout_weight="1" android:background="@android:color/transparent" />
|
|
34
|
+
<TextView android:id="@+id/rn_hit_r0_c3" android:layout_width="0dp" android:layout_height="match_parent" android:layout_weight="1" android:background="@android:color/transparent" />
|
|
57
35
|
</LinearLayout>
|
|
58
36
|
|
|
59
|
-
<!--
|
|
37
|
+
<!-- Row 1 (16.7% - 33.3%) -->
|
|
60
38
|
<LinearLayout
|
|
61
|
-
android:id="@+id/
|
|
39
|
+
android:id="@+id/rn_grid_row_1"
|
|
62
40
|
android:layout_width="match_parent"
|
|
63
41
|
android:layout_height="0dp"
|
|
64
|
-
android:layout_weight="
|
|
65
|
-
android:orientation="
|
|
66
|
-
|
|
67
|
-
<TextView
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
android:layout_weight="1"
|
|
72
|
-
android:background="@android:color/transparent" />
|
|
73
|
-
|
|
74
|
-
<TextView
|
|
75
|
-
android:id="@+id/rn_hit_mid_2"
|
|
76
|
-
android:layout_width="match_parent"
|
|
77
|
-
android:layout_height="0dp"
|
|
78
|
-
android:layout_weight="1"
|
|
79
|
-
android:background="@android:color/transparent" />
|
|
42
|
+
android:layout_weight="1"
|
|
43
|
+
android:orientation="horizontal"
|
|
44
|
+
android:weightSum="3">
|
|
45
|
+
<TextView android:id="@+id/rn_hit_r1_c0" android:layout_width="0dp" android:layout_height="match_parent" android:layout_weight="1" android:background="@android:color/transparent" />
|
|
46
|
+
<TextView android:id="@+id/rn_hit_r1_c1" android:layout_width="0dp" android:layout_height="match_parent" android:layout_weight="1" android:background="@android:color/transparent" />
|
|
47
|
+
<TextView android:id="@+id/rn_hit_r1_c2" android:layout_width="0dp" android:layout_height="match_parent" android:layout_weight="1" android:background="@android:color/transparent" />
|
|
48
|
+
</LinearLayout>
|
|
80
49
|
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
50
|
+
<!-- Row 2 (33.3% - 50.0%) -->
|
|
51
|
+
<LinearLayout
|
|
52
|
+
android:id="@+id/rn_grid_row_2"
|
|
53
|
+
android:layout_width="match_parent"
|
|
54
|
+
android:layout_height="0dp"
|
|
55
|
+
android:layout_weight="1"
|
|
56
|
+
android:orientation="horizontal"
|
|
57
|
+
android:weightSum="3">
|
|
58
|
+
<TextView android:id="@+id/rn_hit_r2_c0" android:layout_width="0dp" android:layout_height="match_parent" android:layout_weight="1" android:background="@android:color/transparent" />
|
|
59
|
+
<TextView android:id="@+id/rn_hit_r2_c1" android:layout_width="0dp" android:layout_height="match_parent" android:layout_weight="1" android:background="@android:color/transparent" />
|
|
60
|
+
<TextView android:id="@+id/rn_hit_r2_c2" android:layout_width="0dp" android:layout_height="match_parent" android:layout_weight="1" android:background="@android:color/transparent" />
|
|
87
61
|
</LinearLayout>
|
|
88
62
|
|
|
89
|
-
<!--
|
|
63
|
+
<!-- Row 3 (50.0% - 66.7%) -->
|
|
90
64
|
<LinearLayout
|
|
91
|
-
android:id="@+id/
|
|
65
|
+
android:id="@+id/rn_grid_row_3"
|
|
92
66
|
android:layout_width="match_parent"
|
|
93
67
|
android:layout_height="0dp"
|
|
94
|
-
android:layout_weight="
|
|
95
|
-
android:orientation="horizontal"
|
|
68
|
+
android:layout_weight="1"
|
|
69
|
+
android:orientation="horizontal"
|
|
70
|
+
android:weightSum="3">
|
|
71
|
+
<TextView android:id="@+id/rn_hit_r3_c0" android:layout_width="0dp" android:layout_height="match_parent" android:layout_weight="1" android:background="@android:color/transparent" />
|
|
72
|
+
<TextView android:id="@+id/rn_hit_r3_c1" android:layout_width="0dp" android:layout_height="match_parent" android:layout_weight="1" android:background="@android:color/transparent" />
|
|
73
|
+
<TextView android:id="@+id/rn_hit_r3_c2" android:layout_width="0dp" android:layout_height="match_parent" android:layout_weight="1" android:background="@android:color/transparent" />
|
|
74
|
+
</LinearLayout>
|
|
96
75
|
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
76
|
+
<!-- Row 4 (66.7% - 83.3%) -->
|
|
77
|
+
<LinearLayout
|
|
78
|
+
android:id="@+id/rn_grid_row_4"
|
|
79
|
+
android:layout_width="match_parent"
|
|
80
|
+
android:layout_height="0dp"
|
|
81
|
+
android:layout_weight="1"
|
|
82
|
+
android:orientation="horizontal"
|
|
83
|
+
android:weightSum="3">
|
|
84
|
+
<TextView android:id="@+id/rn_hit_r4_c0" android:layout_width="0dp" android:layout_height="match_parent" android:layout_weight="1" android:background="@android:color/transparent" />
|
|
85
|
+
<TextView android:id="@+id/rn_hit_r4_c1" android:layout_width="0dp" android:layout_height="match_parent" android:layout_weight="1" android:background="@android:color/transparent" />
|
|
86
|
+
<TextView android:id="@+id/rn_hit_r4_c2" android:layout_width="0dp" android:layout_height="match_parent" android:layout_weight="1" android:background="@android:color/transparent" />
|
|
87
|
+
</LinearLayout>
|
|
103
88
|
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
89
|
+
<!-- Row 5 (83.3% - 100.0%) -->
|
|
90
|
+
<LinearLayout
|
|
91
|
+
android:id="@+id/rn_grid_row_5"
|
|
92
|
+
android:layout_width="match_parent"
|
|
93
|
+
android:layout_height="0dp"
|
|
94
|
+
android:layout_weight="1"
|
|
95
|
+
android:orientation="horizontal"
|
|
96
|
+
android:weightSum="3">
|
|
97
|
+
<TextView android:id="@+id/rn_hit_r5_c0" android:layout_width="0dp" android:layout_height="match_parent" android:layout_weight="1" android:background="@android:color/transparent" />
|
|
98
|
+
<TextView android:id="@+id/rn_hit_r5_c1" android:layout_width="0dp" android:layout_height="match_parent" android:layout_weight="1" android:background="@android:color/transparent" />
|
|
99
|
+
<TextView android:id="@+id/rn_hit_r5_c2" android:layout_width="0dp" android:layout_height="match_parent" android:layout_weight="1" android:background="@android:color/transparent" />
|
|
110
100
|
</LinearLayout>
|
|
111
101
|
</LinearLayout>
|
|
112
102
|
</FrameLayout>
|
package/docs/GUIDE-EN.md
CHANGED
|
@@ -502,6 +502,12 @@ UI.Button({
|
|
|
502
502
|
})
|
|
503
503
|
```
|
|
504
504
|
|
|
505
|
+
> [!IMPORTANT]
|
|
506
|
+
> **Architectural Recommendation for Terminated (Force-Killed) Apps:**
|
|
507
|
+
> - **iOS:** When the main app is force-killed by the user, the JavaScript engine (Hermes/JSC) is terminated. Widget button taps are handled natively by Swift (`AppIntent`) and stored in App Groups. JavaScript callbacks (`registerActionHandler`) **cannot run** until the app is reopened.
|
|
508
|
+
> - **Android:** While `HeadlessJsTaskService` can wake the JS runtime in the background, aggressive OEM battery savers (MIUI, ColorOS, OneUI) may delay or suppress headless execution.
|
|
509
|
+
> - **Production Rule:** For mission-critical actions (e.g., employee attendance check-ins or financial authorizations), adopt an **Offline-First & Local State Queue** pattern: Native widgets record the action in `SharedStorage`, and `App.tsx` reads and synchronizes the queue when the app is next launched.
|
|
510
|
+
|
|
505
511
|
### `UI.ZStack`, `UI.Grid` & `UI.Divider` (Advanced Layout Containers)
|
|
506
512
|
```typescript
|
|
507
513
|
// 1. ZStack: Overlay layers on top of each other
|
|
@@ -610,6 +616,11 @@ UI.Custom('WeatherCard', { city: 'Ho Chi Minh City', temp: '31°C' })
|
|
|
610
616
|
|
|
611
617
|
## 5. Dynamic Island Configuration (iPhone 14 Pro, 15, 16, 17)
|
|
612
618
|
|
|
619
|
+
> [!NOTE]
|
|
620
|
+
> **Platform Differences: iOS Dynamic Island vs. Android Live Updates:**
|
|
621
|
+
> - **iOS:** The `dynamicIsland` configuration maps directly to Apple's hardware Dynamic Island pill (iPhone 14 Pro+) via ActivityKit and SwiftUI (`compactLeading`, `compactTrailing`, `minimal`, `expanded`).
|
|
622
|
+
> - **Android:** Because standard Android devices do not feature Apple's hardware island cutout, this configuration is mapped to an **Ongoing Promoted Notification (`Notification.ProgressStyle`)** with an avatar icon, progress segments, and action buttons on the notification bar.
|
|
623
|
+
|
|
613
624
|
```typescript
|
|
614
625
|
dynamicIsland: {
|
|
615
626
|
compactLeading: UI.HStack(
|
|
@@ -750,6 +761,13 @@ await Widget.setRemoteConfig({
|
|
|
750
761
|
- **Android**: `AlarmManager` schedules `LiveActivityReceiver` (`ACTION_WIDGET_SYNC`), fetches fresh JSON in the background (`goAsync()`), updates `SharedPreferences`, and redraws `DynamicHomeScreenWidgetProvider`.
|
|
751
762
|
- The built-in `{{_lastSyncTime}}` placeholder automatically resolves to the latest sync timestamp (`HH:mm:ss`).
|
|
752
763
|
|
|
764
|
+
> [!NOTE]
|
|
765
|
+
> **Understanding Polling Intervals & OS Widget Budget:**
|
|
766
|
+
> - The `intervalMinutes: 15` option specifies the *desired* refresh cadence. Both iOS and Android apply strict battery and resource policies:
|
|
767
|
+
> - **iOS WidgetKit Budget:** Apple enforces a daily budget (~40 to 70 reloads per day). If the device is in Low Power Mode or the daily quota is exhausted, reloads may be delayed.
|
|
768
|
+
> - **Android Doze Mode:** Batches recurring background alarms to preserve battery health.
|
|
769
|
+
> - **Recommendation:** If your application requires precise, second-by-second updates (e.g., driver location or emergency shifts), always rely on **Server Push Notifications (APNs / FCM)** as the primary transport and treat background polling as a fallback.
|
|
770
|
+
|
|
753
771
|
---
|
|
754
772
|
|
|
755
773
|
## 8. Managing All 3 Push Token Types (APNs & FCM)
|
package/docs/GUIDE-VI.md
CHANGED
|
@@ -502,6 +502,12 @@ UI.Button({
|
|
|
502
502
|
})
|
|
503
503
|
```
|
|
504
504
|
|
|
505
|
+
> [!IMPORTANT]
|
|
506
|
+
> **Khuyến nghị kiến trúc khi xử lý Action lúc App bị Force-Kill (Termination):**
|
|
507
|
+
> - **Trên iOS:** Khi người dùng vuốt tắt ứng dụng hoàn toàn (Force-Kill), JavaScript Engine (Hermes/JSC) sẽ bị tiêu diệt. Lúc này, việc bấm nút trên Widget sẽ do Native Swift (`AppIntent`) xử lý độc lập và ghi nhận trạng thái vào App Group. JS callback (`registerActionHandler`) sẽ **không thể chạy** cho đến khi ứng dụng được người dùng mở lại.
|
|
508
|
+
> - **Trên Android:** Thư viện hỗ trợ `HeadlessJsTaskService` để thức tỉnh JS thread trong nền. Tuy nhiên, trên một số dòng máy có cơ chế quản lý pin nghiêm ngặt (MIUI, ColorOS, OneUI), tiến trình nền vẫn có thể bị hạn chế.
|
|
509
|
+
> - **Quy tắc thiết kế cho Production:** Với các nghiệp vụ sống còn (như **Chấm công**, thanh toán, gửi đơn từ quan trọng), không nên thiết kế nghiệp vụ phụ thuộc 100% vào việc JS callback phải chạy khi app bị kill. Hãy ưu tiên thiết kế theo mô hình **Offline-First & Local State Queue**: Native Widget ghi nhận hành động vào `SharedStorage` (App Group / SharedPreferences), và khi người dùng khởi động lại ứng dụng, `App.tsx` sẽ đọc queue này và đồng bộ an toàn lên Server!
|
|
510
|
+
|
|
505
511
|
### `UI.ZStack`, `UI.Grid` & `UI.Divider` (Bố cục nâng cao)
|
|
506
512
|
```typescript
|
|
507
513
|
// 1. ZStack: Xếp chồng các lớp (Overlay)
|
|
@@ -611,6 +617,11 @@ UI.Custom('WeatherCard', { city: 'TP.HCM', temp: '31°C' })
|
|
|
611
617
|
|
|
612
618
|
## 5. Cấu hình Dynamic Island (iPhone 14 Pro, 15, 16, 17)
|
|
613
619
|
|
|
620
|
+
> [!NOTE]
|
|
621
|
+
> **Khác biệt nền tảng: iOS Dynamic Island vs Android Live Updates:**
|
|
622
|
+
> - **Trên iOS:** Khối cấu hình `dynamicIsland` tương tác trực tiếp với phần cứng Dynamic Island (viên thuốc trên iPhone 14 Pro trở lên) thông qua ActivityKit và SwiftUI (`compactLeading`, `compactTrailing`, `minimal`, `expanded`).
|
|
623
|
+
> - **Trên Android:** Do hệ điều hành Android gốc không có phần cứng Dynamic Island của Apple, cấu hình này được thư viện tự động ánh xạ sang **Ongoing Promoted Notification (`Notification.ProgressStyle`)** hiển thị thường trực trên thanh trạng thái với đầy đủ Avatar tròn, thanh tiến trình chia chặng và nút bấm tương tác.
|
|
624
|
+
|
|
614
625
|
```typescript
|
|
615
626
|
dynamicIsland: {
|
|
616
627
|
compactLeading: UI.HStack(
|
|
@@ -751,6 +762,13 @@ await Widget.setRemoteConfig({
|
|
|
751
762
|
- Trên **Android**: `AlarmManager` tự động đánh thức `LiveActivityReceiver` (`ACTION_WIDGET_SYNC`), tải JSON mới và vẽ lại `DynamicHomeScreenWidgetProvider`.
|
|
752
763
|
- Biến đặc biệt `{{_lastSyncTime}}` luôn tự động cập nhật thành giờ đồng bộ mới nhất (`HH:mm:ss`).
|
|
753
764
|
|
|
765
|
+
> [!NOTE]
|
|
766
|
+
> **Về chu kỳ gọi API và giới hạn tài nguyên hệ điều hành (Widget Budget):**
|
|
767
|
+
> - Tham số `intervalMinutes: 15` là thời gian mong muốn đề xuất cho hệ điều hành. Cả iOS và Android đều áp dụng cơ chế quản lý năng lượng nghiêm ngặt:
|
|
768
|
+
> - **iOS WidgetKit Budget:** Apple cấp hạn mức reload Widget (khoảng 40 - 70 lần/ngày). Nếu thiết bị bật chế độ *Tiết kiệm pin (Low Power Mode)* hoặc đã cạn budget trong ngày, iOS có thể giãn cách thời gian gọi API.
|
|
769
|
+
> - **Android Doze Mode:** Hệ thống sẽ gom các tác vụ nền định kỳ để chạy cùng lúc nhằm tiết kiệm pin.
|
|
770
|
+
> - **Khuyến nghị:** Nếu ứng dụng của bạn yêu cầu cập nhật chính xác từng giây/phút (như vị trí tài xế, tiến trình đơn hàng), **Server Push Notification (APNs / FCM)** là giải pháp tối ưu nhất, tính năng polling `setRemoteConfig` là giải pháp bổ trợ định kỳ.
|
|
771
|
+
|
|
754
772
|
---
|
|
755
773
|
|
|
756
774
|
## 8. Quản lý 3 loại Push Token (APNs & FCM) cho Live Activity
|
package/docs/index.html
ADDED
|
@@ -0,0 +1,405 @@
|
|
|
1
|
+
<!DOCTYPE html>
|
|
2
|
+
<html lang="vi" class="dark">
|
|
3
|
+
<head>
|
|
4
|
+
<meta charset="UTF-8">
|
|
5
|
+
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
6
|
+
<title>react-native-live-widgets — Documentation & AI Agent Hub</title>
|
|
7
|
+
<meta name="description" content="All-in-One Declarative Engine for Live Activities, Dynamic Island & Interactive Home Screen Widgets in React Native & Expo.">
|
|
8
|
+
<link rel="icon" href="https://raw.githubusercontent.com/React-Native-Vu/react-native-live-widgets/dev/assets/dynamic_island_expanded.png" type="image/png">
|
|
9
|
+
<!-- Tailwind CSS CDN -->
|
|
10
|
+
<script src="https://cdn.tailwindcss.com"></script>
|
|
11
|
+
<script>
|
|
12
|
+
tailwind.config = {
|
|
13
|
+
darkMode: 'class',
|
|
14
|
+
theme: {
|
|
15
|
+
extend: {
|
|
16
|
+
colors: {
|
|
17
|
+
brand: {
|
|
18
|
+
50: '#F0F9FF',
|
|
19
|
+
100: '#E0F2FE',
|
|
20
|
+
500: '#0284C7',
|
|
21
|
+
600: '#0284C7',
|
|
22
|
+
700: '#0369A1',
|
|
23
|
+
},
|
|
24
|
+
darkBg: '#090D16',
|
|
25
|
+
cardBg: '#111827',
|
|
26
|
+
cardBorder: '#1F2937'
|
|
27
|
+
}
|
|
28
|
+
}
|
|
29
|
+
}
|
|
30
|
+
}
|
|
31
|
+
</script>
|
|
32
|
+
<!-- Lucide Icons -->
|
|
33
|
+
<script src="https://unpkg.com/lucide@latest"></script>
|
|
34
|
+
<!-- PrismJS for syntax highlighting -->
|
|
35
|
+
<link href="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/themes/prism-tomorrow.min.css" rel="stylesheet" />
|
|
36
|
+
<script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/prism.min.js"></script>
|
|
37
|
+
<script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/components/prism-typescript.min.js"></script>
|
|
38
|
+
<script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/components/prism-bash.min.js"></script>
|
|
39
|
+
<script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/components/prism-json.min.js"></script>
|
|
40
|
+
<style>
|
|
41
|
+
pre[class*="language-"] {
|
|
42
|
+
background: #0D1117 !important;
|
|
43
|
+
border: 1px solid #21262D;
|
|
44
|
+
border-radius: 0.75rem;
|
|
45
|
+
margin: 1rem 0;
|
|
46
|
+
font-size: 0.875rem;
|
|
47
|
+
}
|
|
48
|
+
code[class*="language-"] {
|
|
49
|
+
font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", monospace;
|
|
50
|
+
}
|
|
51
|
+
.custom-scrollbar::-webkit-scrollbar {
|
|
52
|
+
width: 6px;
|
|
53
|
+
}
|
|
54
|
+
.custom-scrollbar::-webkit-scrollbar-thumb {
|
|
55
|
+
background: #374151;
|
|
56
|
+
border-radius: 3px;
|
|
57
|
+
}
|
|
58
|
+
</style>
|
|
59
|
+
</head>
|
|
60
|
+
<body class="bg-darkBg text-slate-200 min-h-screen flex flex-col font-sans antialiased selection:bg-sky-500 selection:text-white">
|
|
61
|
+
|
|
62
|
+
<!-- Top Navigation Header -->
|
|
63
|
+
<header class="sticky top-0 z-50 backdrop-blur-md bg-darkBg/80 border-b border-cardBorder">
|
|
64
|
+
<div class="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8 h-16 flex items-center justify-between">
|
|
65
|
+
<div class="flex items-center space-x-3">
|
|
66
|
+
<span class="text-2xl">🚀</span>
|
|
67
|
+
<a href="#" class="font-bold text-lg text-white hover:text-sky-400 transition">
|
|
68
|
+
react-native-live-widgets
|
|
69
|
+
</a>
|
|
70
|
+
<span class="inline-flex items-center px-2.5 py-0.5 rounded-full text-xs font-semibold bg-sky-500/10 text-sky-400 border border-sky-500/20">
|
|
71
|
+
v1.1.0
|
|
72
|
+
</span>
|
|
73
|
+
<span class="hidden sm:inline-flex items-center px-2 py-0.5 rounded-full text-xs font-medium bg-emerald-500/10 text-emerald-400 border border-emerald-500/20">
|
|
74
|
+
Expo Ready
|
|
75
|
+
</span>
|
|
76
|
+
</div>
|
|
77
|
+
|
|
78
|
+
<nav class="flex items-center space-x-4">
|
|
79
|
+
<a href="#quick-start" class="text-sm text-slate-300 hover:text-white hidden md:inline">Cài đặt</a>
|
|
80
|
+
<a href="#dsl-catalog" class="text-sm text-slate-300 hover:text-white hidden md:inline">Declarative DSL</a>
|
|
81
|
+
<a href="#llms-ai" class="text-sm text-sky-400 font-medium hover:text-sky-300 flex items-center space-x-1">
|
|
82
|
+
<i data-lucide="bot" class="w-4 h-4"></i>
|
|
83
|
+
<span>AI / llms.txt</span>
|
|
84
|
+
</a>
|
|
85
|
+
<a href="https://github.com/React-Native-Vu/LiveWidgetsExampleExpo" target="_blank" class="text-sm text-slate-300 hover:text-white hidden lg:inline">
|
|
86
|
+
Expo Demo
|
|
87
|
+
</a>
|
|
88
|
+
<a href="https://github.com/React-Native-Vu/react-native-live-widgets" target="_blank" class="p-2 text-slate-400 hover:text-white transition" title="GitHub">
|
|
89
|
+
<i data-lucide="github" class="w-5 h-5"></i>
|
|
90
|
+
</a>
|
|
91
|
+
<a href="https://www.npmjs.com/package/react-native-live-widgets" target="_blank" class="p-2 text-red-400 hover:text-red-300 transition" title="npm">
|
|
92
|
+
<svg class="w-5 h-5 fill-current" viewBox="0 0 780 250"><path d="M240,250h100v-50h100V0H240V250z M340,50h50v100h-50V50z M480,0v200h100V50h50v150h50V50h50v150h50V0H480z M0,200h100V50h50v150h50V0H0V200z"/></svg>
|
|
93
|
+
</a>
|
|
94
|
+
</nav>
|
|
95
|
+
</div>
|
|
96
|
+
</header>
|
|
97
|
+
|
|
98
|
+
<!-- Hero Section -->
|
|
99
|
+
<section class="relative overflow-hidden pt-12 pb-16 lg:pt-20 lg:pb-24 border-b border-cardBorder bg-gradient-to-b from-sky-950/20 to-transparent">
|
|
100
|
+
<div class="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8 text-center">
|
|
101
|
+
<div class="inline-flex items-center space-x-2 px-3 py-1 rounded-full bg-slate-800/80 border border-slate-700 text-xs text-slate-300 mb-6">
|
|
102
|
+
<span>✨ Hỗ trợ 100% Expo Config Plugin, EAS Build & Bare React Native</span>
|
|
103
|
+
</div>
|
|
104
|
+
<h1 class="text-4xl sm:text-5xl lg:text-6xl font-extrabold text-white tracking-tight leading-tight">
|
|
105
|
+
Live Activities & Dynamic Island <br>
|
|
106
|
+
<span class="text-transparent bg-clip-text bg-gradient-to-r from-sky-400 via-teal-300 to-indigo-400">
|
|
107
|
+
Chỉ bằng TypeScript Declarative
|
|
108
|
+
</span>
|
|
109
|
+
</h1>
|
|
110
|
+
<p class="mt-6 text-lg sm:text-xl text-slate-400 max-w-3xl mx-auto">
|
|
111
|
+
Tạo tiện ích Home Screen Widgets và Live Activities Native cho cả iOS và Android mà
|
|
112
|
+
<strong>không cần viết 1 dòng mã Swift hay Kotlin</strong>. Tích hợp sẵn chuẩn cho AI Agent & LLMs.
|
|
113
|
+
</p>
|
|
114
|
+
|
|
115
|
+
<div class="mt-8 flex flex-wrap justify-center gap-4">
|
|
116
|
+
<a href="#quick-start" class="px-6 py-3 rounded-xl bg-sky-600 hover:bg-sky-500 text-white font-semibold shadow-lg shadow-sky-600/25 transition flex items-center space-x-2">
|
|
117
|
+
<i data-lucide="play" class="w-4 h-4"></i>
|
|
118
|
+
<span>Bắt đầu ngay</span>
|
|
119
|
+
</a>
|
|
120
|
+
<a href="https://github.com/React-Native-Vu/LiveWidgetsExampleExpo" target="_blank" class="px-6 py-3 rounded-xl bg-slate-800 hover:bg-slate-700 text-slate-200 border border-slate-700 font-semibold transition flex items-center space-x-2">
|
|
121
|
+
<i data-lucide="smartphone" class="w-4 h-4"></i>
|
|
122
|
+
<span>Xem Expo Demo</span>
|
|
123
|
+
</a>
|
|
124
|
+
<a href="llms.txt" target="_blank" class="px-6 py-3 rounded-xl bg-indigo-950/60 hover:bg-indigo-900/60 text-indigo-300 border border-indigo-700/50 font-semibold transition flex items-center space-x-2">
|
|
125
|
+
<i data-lucide="file-code" class="w-4 h-4"></i>
|
|
126
|
+
<span>Tài liệu cho AI (llms.txt)</span>
|
|
127
|
+
</a>
|
|
128
|
+
</div>
|
|
129
|
+
</div>
|
|
130
|
+
</section>
|
|
131
|
+
|
|
132
|
+
<!-- Main Content Layout -->
|
|
133
|
+
<div class="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8 py-10 flex-1 grid grid-cols-1 lg:grid-cols-4 gap-8">
|
|
134
|
+
|
|
135
|
+
<!-- Sidebar Navigation -->
|
|
136
|
+
<aside class="hidden lg:block lg:col-span-1 space-y-6 sticky top-24 h-[calc(100vh-8rem)] overflow-y-auto custom-scrollbar pr-2">
|
|
137
|
+
<div>
|
|
138
|
+
<h4 class="text-xs font-semibold text-slate-400 uppercase tracking-wider mb-2">Bắt đầu</h4>
|
|
139
|
+
<ul class="space-y-1.5 text-sm">
|
|
140
|
+
<li><a href="#quick-start" class="text-sky-400 font-medium block py-1 hover:text-sky-300">Cài đặt & Thiết lập</a></li>
|
|
141
|
+
<li><a href="#expo-setup" class="text-slate-400 hover:text-slate-200 block py-1">Dành cho Expo (CNG)</a></li>
|
|
142
|
+
<li><a href="#bare-rn-setup" class="text-slate-400 hover:text-slate-200 block py-1">Dành cho Bare React Native</a></li>
|
|
143
|
+
</ul>
|
|
144
|
+
</div>
|
|
145
|
+
|
|
146
|
+
<div>
|
|
147
|
+
<h4 class="text-xs font-semibold text-slate-400 uppercase tracking-wider mb-2">Declarative UI DSL</h4>
|
|
148
|
+
<ul class="space-y-1.5 text-sm">
|
|
149
|
+
<li><a href="#dsl-containers" class="text-slate-400 hover:text-slate-200 block py-1">VStack / HStack / ZStack</a></li>
|
|
150
|
+
<li><a href="#dsl-timer" class="text-slate-400 hover:text-slate-200 block py-1">UI.Timer (Phần cứng)</a></li>
|
|
151
|
+
<li><a href="#dsl-progress" class="text-slate-400 hover:text-slate-200 block py-1">UI.Progress (Bar, Circular)</a></li>
|
|
152
|
+
<li><a href="#dsl-equalizer" class="text-slate-400 hover:text-slate-200 block py-1">UI.Equalizer (Sóng nhạc)</a></li>
|
|
153
|
+
<li><a href="#dsl-interactive" class="text-slate-400 hover:text-slate-200 block py-1">UI.Button (Tương tác 2 chiều)</a></li>
|
|
154
|
+
</ul>
|
|
155
|
+
</div>
|
|
156
|
+
|
|
157
|
+
<div>
|
|
158
|
+
<h4 class="text-xs font-semibold text-slate-400 uppercase tracking-wider mb-2">AI Agent & LLM</h4>
|
|
159
|
+
<ul class="space-y-1.5 text-sm">
|
|
160
|
+
<li><a href="#llms-ai" class="text-indigo-400 hover:text-indigo-300 font-medium block py-1">llms.txt Standard</a></li>
|
|
161
|
+
<li><a href="#agent-skill" class="text-indigo-400 hover:text-indigo-300 block py-1">Agent Skill (SKILL.md)</a></li>
|
|
162
|
+
</ul>
|
|
163
|
+
</div>
|
|
164
|
+
|
|
165
|
+
<div>
|
|
166
|
+
<h4 class="text-xs font-semibold text-slate-400 uppercase tracking-wider mb-2">Tài nguyên & Demo</h4>
|
|
167
|
+
<ul class="space-y-1.5 text-sm">
|
|
168
|
+
<li><a href="https://github.com/React-Native-Vu/LiveWidgetsExampleExpo" target="_blank" class="text-slate-400 hover:text-slate-200 block py-1">Expo Demo GitHub ↗</a></li>
|
|
169
|
+
<li><a href="https://github.com/React-Native-Vu/LiveWidgetsExample" target="_blank" class="text-slate-400 hover:text-slate-200 block py-1">Bare RN Demo GitHub ↗</a></li>
|
|
170
|
+
<li><a href="GUIDE-VI.md" target="_blank" class="text-slate-400 hover:text-slate-200 block py-1">Tài liệu chi tiết (Tiếng Việt) ↗</a></li>
|
|
171
|
+
<li><a href="GUIDE-EN.md" target="_blank" class="text-slate-400 hover:text-slate-200 block py-1">Full English Guide ↗</a></li>
|
|
172
|
+
</ul>
|
|
173
|
+
</div>
|
|
174
|
+
</aside>
|
|
175
|
+
|
|
176
|
+
<!-- Main Content Area -->
|
|
177
|
+
<main class="lg:col-span-3 space-y-12">
|
|
178
|
+
|
|
179
|
+
<!-- Section: Quick Start -->
|
|
180
|
+
<section id="quick-start" class="space-y-6">
|
|
181
|
+
<h2 class="text-2xl sm:text-3xl font-bold text-white flex items-center space-x-2">
|
|
182
|
+
<i data-lucide="zap" class="w-6 h-6 text-sky-400"></i>
|
|
183
|
+
<span>Cài đặt & Thiết lập tự động</span>
|
|
184
|
+
</h2>
|
|
185
|
+
|
|
186
|
+
<p class="text-slate-300">
|
|
187
|
+
Thư viện cung cấp bộ công cụ <strong>All-in-One CLI Scaffolder</strong> giúp tự động tạo Xcode Extension target,
|
|
188
|
+
cấu hình App Groups và Android permissions chỉ với 1 câu lệnh duy nhất.
|
|
189
|
+
</p>
|
|
190
|
+
|
|
191
|
+
<!-- Expo Tab -->
|
|
192
|
+
<div id="expo-setup" class="bg-cardBg border border-cardBorder rounded-xl p-5 space-y-4">
|
|
193
|
+
<div class="flex items-center justify-between">
|
|
194
|
+
<span class="font-bold text-white flex items-center space-x-2">
|
|
195
|
+
<span class="w-2.5 h-2.5 rounded-full bg-emerald-400"></span>
|
|
196
|
+
<span>1. Quy trình dành cho Expo (SDK 50, 51, 52, 58+)</span>
|
|
197
|
+
</span>
|
|
198
|
+
<span class="text-xs bg-emerald-500/10 text-emerald-400 px-2 py-0.5 rounded border border-emerald-500/20">Config Plugin</span>
|
|
199
|
+
</div>
|
|
200
|
+
|
|
201
|
+
<pre><code class="language-bash"># Bước 1: Cài đặt package
|
|
202
|
+
npx expo install react-native-live-widgets
|
|
203
|
+
|
|
204
|
+
# Bước 2: Thêm plugin vào app.json
|
|
205
|
+
# (xem mẫu cấu hình bên dưới)
|
|
206
|
+
|
|
207
|
+
# Bước 3: Sinh thư mục native
|
|
208
|
+
npx expo prebuild
|
|
209
|
+
|
|
210
|
+
# Bước 4: Tự động cấu hình Widget Extension target & App Groups
|
|
211
|
+
npx react-native-live-widgets init --group group.com.yourcompany.app
|
|
212
|
+
|
|
213
|
+
# Bước 5: Chạy ứng dụng trên Simulator
|
|
214
|
+
npx expo run:ios</code></pre>
|
|
215
|
+
|
|
216
|
+
<p class="text-xs text-slate-400">Cấu hình plugin trong <code class="text-sky-300">app.json</code>:</p>
|
|
217
|
+
<pre><code class="language-json">{
|
|
218
|
+
"expo": {
|
|
219
|
+
"plugins": [
|
|
220
|
+
[
|
|
221
|
+
"react-native-live-widgets",
|
|
222
|
+
{
|
|
223
|
+
"appGroup": "group.com.yourcompany.app",
|
|
224
|
+
"enableLiveActivities": true,
|
|
225
|
+
"frequentUpdates": true
|
|
226
|
+
}
|
|
227
|
+
]
|
|
228
|
+
]
|
|
229
|
+
}
|
|
230
|
+
}</code></pre>
|
|
231
|
+
</div>
|
|
232
|
+
|
|
233
|
+
<!-- Bare RN Tab -->
|
|
234
|
+
<div id="bare-rn-setup" class="bg-cardBg border border-cardBorder rounded-xl p-5 space-y-4">
|
|
235
|
+
<span class="font-bold text-white flex items-center space-x-2">
|
|
236
|
+
<span class="w-2.5 h-2.5 rounded-full bg-sky-400"></span>
|
|
237
|
+
<span>2. Quy trình dành cho Bare React Native CLI</span>
|
|
238
|
+
</span>
|
|
239
|
+
<pre><code class="language-bash">npm install react-native-live-widgets
|
|
240
|
+
# Tự động inject Xcode target, entitlements, podfile và android permissions
|
|
241
|
+
npx react-native-live-widgets init --group group.com.yourcompany.app
|
|
242
|
+
npx react-native run-ios</code></pre>
|
|
243
|
+
</div>
|
|
244
|
+
</section>
|
|
245
|
+
|
|
246
|
+
<!-- Section: Declarative UI DSL -->
|
|
247
|
+
<section id="dsl-catalog" class="space-y-6">
|
|
248
|
+
<h2 class="text-2xl sm:text-3xl font-bold text-white flex items-center space-x-2">
|
|
249
|
+
<i data-lucide="layers" class="w-6 h-6 text-sky-400"></i>
|
|
250
|
+
<span>Declarative UI Engine (`UI.*`)</span>
|
|
251
|
+
</h2>
|
|
252
|
+
<p class="text-slate-300">
|
|
253
|
+
Không cần viết SwiftUI hay Kotlin RemoteViews! Khai báo cây giao diện trực tiếp trong TypeScript và hệ thống sẽ tự động ánh xạ sang Native:
|
|
254
|
+
</p>
|
|
255
|
+
|
|
256
|
+
<div class="grid grid-cols-1 md:grid-cols-2 gap-4">
|
|
257
|
+
<!-- Card: Live Activity Example -->
|
|
258
|
+
<div class="bg-cardBg border border-cardBorder rounded-xl p-4 space-y-3">
|
|
259
|
+
<div class="flex items-center justify-between">
|
|
260
|
+
<span class="text-sm font-semibold text-white">🚀 Live Activity & Dynamic Island</span>
|
|
261
|
+
<span class="text-xs text-sky-400 bg-sky-500/10 px-2 py-0.5 rounded">iOS 16.1+</span>
|
|
262
|
+
</div>
|
|
263
|
+
<pre><code class="language-typescript">await LiveActivity.start({
|
|
264
|
+
activityName: 'Delivery',
|
|
265
|
+
appGroup: 'group.com.myapp',
|
|
266
|
+
layout: UI.VStack({
|
|
267
|
+
padding: 16,
|
|
268
|
+
backgroundColor: '#0F172A',
|
|
269
|
+
children: [
|
|
270
|
+
UI.Text('Tài xế đang giao đơn', {
|
|
271
|
+
color: '#FFFFFF',
|
|
272
|
+
fontSize: 15,
|
|
273
|
+
fontWeight: 'bold'
|
|
274
|
+
}),
|
|
275
|
+
UI.Progress({
|
|
276
|
+
style: 'bar',
|
|
277
|
+
value: 0.7,
|
|
278
|
+
tintColor: '#38BDF8',
|
|
279
|
+
height: 6
|
|
280
|
+
})
|
|
281
|
+
]
|
|
282
|
+
}),
|
|
283
|
+
dynamicIsland: {
|
|
284
|
+
compactLeading: UI.Text('☕', { fontSize: 13 }),
|
|
285
|
+
compactTrailing: UI.Text('12m', { color: '#38BDF8', fontWeight: 'bold' }),
|
|
286
|
+
expanded: {
|
|
287
|
+
leading: UI.Text('COFFEE EXPRESS', { fontSize: 11 }),
|
|
288
|
+
trailing: UI.Text('12 mins', { fontSize: 16, fontWeight: 'bold' })
|
|
289
|
+
}
|
|
290
|
+
}
|
|
291
|
+
});</code></pre>
|
|
292
|
+
</div>
|
|
293
|
+
|
|
294
|
+
<!-- Card: Interactive Widget Example -->
|
|
295
|
+
<div class="bg-cardBg border border-cardBorder rounded-xl p-4 space-y-3">
|
|
296
|
+
<div class="flex items-center justify-between">
|
|
297
|
+
<span class="text-sm font-semibold text-white">⚡ Home Screen Widget Tương Tác 2 Chiều</span>
|
|
298
|
+
<span class="text-xs text-emerald-400 bg-emerald-500/10 px-2 py-0.5 rounded">AppIntents</span>
|
|
299
|
+
</div>
|
|
300
|
+
<pre><code class="language-typescript">// Cập nhật Home Screen Widget với nút bấm tương tác
|
|
301
|
+
Widget.reload('main', {
|
|
302
|
+
layout: UI.VStack({
|
|
303
|
+
padding: 14,
|
|
304
|
+
backgroundColor: '#0F172A',
|
|
305
|
+
alignment: 'center',
|
|
306
|
+
children: [
|
|
307
|
+
UI.Text('BỘ ĐẾM TIỆN ÍCH', { color: '#94A3B8', fontSize: 11 }),
|
|
308
|
+
UI.Text(`${counter}`, { color: '#38BDF8', fontSize: 32, fontWeight: 'heavy' }),
|
|
309
|
+
UI.Button({
|
|
310
|
+
title: '+1 TĂNG SỐ',
|
|
311
|
+
actionId: 'INCREMENT',
|
|
312
|
+
backgroundColor: '#0284C7',
|
|
313
|
+
color: '#FFFFFF'
|
|
314
|
+
})
|
|
315
|
+
]
|
|
316
|
+
})
|
|
317
|
+
});
|
|
318
|
+
|
|
319
|
+
// Lắng nghe khi người dùng bấm nút trên mặt Widget
|
|
320
|
+
LiveActivity.registerActionHandler((actionId) => {
|
|
321
|
+
if (actionId === 'INCREMENT') {
|
|
322
|
+
setCounter(c => c + 1);
|
|
323
|
+
}
|
|
324
|
+
});</code></pre>
|
|
325
|
+
</div>
|
|
326
|
+
</div>
|
|
327
|
+
</section>
|
|
328
|
+
|
|
329
|
+
<!-- Section: AI Agent & LLM Hub -->
|
|
330
|
+
<section id="llms-ai" class="space-y-6 pt-4 border-t border-cardBorder">
|
|
331
|
+
<div class="flex items-center space-x-3">
|
|
332
|
+
<div class="p-2 rounded-lg bg-indigo-500/10 border border-indigo-500/20 text-indigo-400">
|
|
333
|
+
<i data-lucide="bot" class="w-6 h-6"></i>
|
|
334
|
+
</div>
|
|
335
|
+
<div>
|
|
336
|
+
<h2 class="text-2xl sm:text-3xl font-bold text-white">AI Agent & LLM Hub (llms.txt)</h2>
|
|
337
|
+
<p class="text-sm text-slate-400">Tối ưu 100% cho các mô hình AI: ChatGPT, Claude, Copilot, Cursor, Antigravity</p>
|
|
338
|
+
</div>
|
|
339
|
+
</div>
|
|
340
|
+
|
|
341
|
+
<p class="text-slate-300">
|
|
342
|
+
Thư viện tuân thủ chuẩn mở <strong><a href="https://llmstxt.org" target="_blank" class="text-sky-400 hover:underline">llms.txt</a></strong>,
|
|
343
|
+
cho phép bất kỳ AI agent nào tự động đọc cấu trúc, API cheat sheet và các nguyên tắc kiến trúc để viết code widget chuẩn xác mà không bị ảo giác (hallucination).
|
|
344
|
+
</p>
|
|
345
|
+
|
|
346
|
+
<div class="grid grid-cols-1 md:grid-cols-2 gap-4">
|
|
347
|
+
<div class="bg-cardBg border border-indigo-900/40 rounded-xl p-5 space-y-3">
|
|
348
|
+
<div class="flex items-center justify-between">
|
|
349
|
+
<span class="font-bold text-white flex items-center space-x-2">
|
|
350
|
+
<i data-lucide="file-text" class="w-4 h-4 text-indigo-400"></i>
|
|
351
|
+
<span>Tập tin llms.txt</span>
|
|
352
|
+
</span>
|
|
353
|
+
<a href="llms.txt" target="_blank" class="text-xs bg-indigo-500/10 text-indigo-300 border border-indigo-500/30 px-2 py-0.5 rounded hover:bg-indigo-500/20">
|
|
354
|
+
Xem file raw ↗
|
|
355
|
+
</a>
|
|
356
|
+
</div>
|
|
357
|
+
<p class="text-xs text-slate-400">
|
|
358
|
+
Chứa tóm tắt kiến trúc, bảng hàm DSL và 5 quy tắc vàng giúp AI sinh mã TypeScript widget an toàn.
|
|
359
|
+
</p>
|
|
360
|
+
<pre><code class="language-bash">curl -s https://react-native-vu.github.io/react-native-live-widgets/llms.txt</code></pre>
|
|
361
|
+
</div>
|
|
362
|
+
|
|
363
|
+
<div id="agent-skill" class="bg-cardBg border border-indigo-900/40 rounded-xl p-5 space-y-3">
|
|
364
|
+
<div class="flex items-center justify-between">
|
|
365
|
+
<span class="font-bold text-white flex items-center space-x-2">
|
|
366
|
+
<i data-lucide="cpu" class="w-4 h-4 text-sky-400"></i>
|
|
367
|
+
<span>Agent Skill (SKILL.md)</span>
|
|
368
|
+
</span>
|
|
369
|
+
<a href="https://github.com/React-Native-Vu/react-native-live-widgets/blob/dev/skills/react-native-live-widgets/SKILL.md" target="_blank" class="text-xs bg-sky-500/10 text-sky-300 border border-sky-500/30 px-2 py-0.5 rounded hover:bg-sky-500/20">
|
|
370
|
+
Xem SKILL.md ↗
|
|
371
|
+
</a>
|
|
372
|
+
</div>
|
|
373
|
+
<p class="text-xs text-slate-400">
|
|
374
|
+
Tương thích trực tiếp với các hệ thống coding agent như Antigravity, Claude Code, Cursor Rules để kích hoạt tự động theo ngữ cảnh.
|
|
375
|
+
</p>
|
|
376
|
+
<pre><code class="language-bash"># Vị trí skill trong dự án của bạn
|
|
377
|
+
.agents/skills/react-native-live-widgets/SKILL.md</code></pre>
|
|
378
|
+
</div>
|
|
379
|
+
</div>
|
|
380
|
+
</section>
|
|
381
|
+
|
|
382
|
+
</main>
|
|
383
|
+
</div>
|
|
384
|
+
|
|
385
|
+
<!-- Footer -->
|
|
386
|
+
<footer class="border-t border-cardBorder bg-cardBg/50 py-8 mt-16">
|
|
387
|
+
<div class="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8 flex flex-col sm:flex-row items-center justify-between text-xs text-slate-400 gap-4">
|
|
388
|
+
<div>
|
|
389
|
+
Phát triển bởi <strong class="text-white">vu-tran</strong> • Giấy phép MIT •
|
|
390
|
+
<a href="https://github.com/React-Native-Vu/react-native-live-widgets" class="text-sky-400 hover:underline">GitHub Repository</a>
|
|
391
|
+
</div>
|
|
392
|
+
<div class="flex items-center space-x-4">
|
|
393
|
+
<a href="llms.txt" class="hover:text-white transition">llms.txt</a>
|
|
394
|
+
<a href="llms-full.txt" class="hover:text-white transition">llms-full.txt</a>
|
|
395
|
+
<a href="EXPO-GUIDE-VI.md" class="hover:text-white transition">Expo Guide</a>
|
|
396
|
+
</div>
|
|
397
|
+
</div>
|
|
398
|
+
</footer>
|
|
399
|
+
|
|
400
|
+
<script>
|
|
401
|
+
// Initialize Lucide icons
|
|
402
|
+
lucide.createIcons();
|
|
403
|
+
</script>
|
|
404
|
+
</body>
|
|
405
|
+
</html>
|
|
@@ -0,0 +1,118 @@
|
|
|
1
|
+
# react-native-live-widgets — Full AI Reference Manual (llms-full.txt)
|
|
2
|
+
|
|
3
|
+
> Comprehensive reference guide for Large Language Models (LLMs) and autonomous AI coding agents implementing Live Activities, Dynamic Island, and Home Screen Widgets in React Native and Expo.
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## 1. High-Level Architecture
|
|
8
|
+
|
|
9
|
+
`react-native-live-widgets` solves cross-platform widget development by abstracting native complexity behind a high-performance JSON layout protocol and declarative DSL:
|
|
10
|
+
- **iOS 16.1+**: Maps `UI.*` nodes to SwiftUI primitives in WidgetKit (`DynamicNodeView.swift`). Supports ActivityKit for Live Activities on Lock Screen and Dynamic Island (expanded, compactLeading, compactTrailing, minimal). Supports iOS 17+ interactive `AppIntents`.
|
|
11
|
+
- **Android API 24 -> Android 16 (API 36)**: Maps `UI.*` nodes to a high-DPI 2D `Canvas` renderer (`DynamicWidgetCanvasRenderer.kt`) for Home Screen `AppWidgetProvider`, and uses `Notification.ProgressStyle` / Ongoing Notifications for Live Activities with interactive action buttons and segmented progress bars.
|
|
12
|
+
- **Shared Storage**: Uses iOS `UserDefaults(suiteName: appGroup)` and Android `SharedPreferences` to synchronize state with zero latency.
|
|
13
|
+
|
|
14
|
+
---
|
|
15
|
+
|
|
16
|
+
## 2. API Signature & Type Definitions
|
|
17
|
+
|
|
18
|
+
```typescript
|
|
19
|
+
export interface StartActivityOptions {
|
|
20
|
+
activityName: string;
|
|
21
|
+
appGroup?: string;
|
|
22
|
+
layout: WidgetNode;
|
|
23
|
+
dynamicIsland?: {
|
|
24
|
+
compactLeading?: WidgetNode;
|
|
25
|
+
compactTrailing?: WidgetNode;
|
|
26
|
+
minimal?: WidgetNode;
|
|
27
|
+
expanded?: {
|
|
28
|
+
leading?: WidgetNode;
|
|
29
|
+
trailing?: WidgetNode;
|
|
30
|
+
center?: WidgetNode;
|
|
31
|
+
bottom?: WidgetNode;
|
|
32
|
+
};
|
|
33
|
+
};
|
|
34
|
+
attributes?: Record<string, any>;
|
|
35
|
+
androidConfig?: {
|
|
36
|
+
channelId?: string;
|
|
37
|
+
channelName?: string;
|
|
38
|
+
notificationId?: number;
|
|
39
|
+
smallIcon?: string;
|
|
40
|
+
ongoing?: boolean;
|
|
41
|
+
color?: string;
|
|
42
|
+
};
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
export interface WidgetLayoutConfig {
|
|
46
|
+
layout?: WidgetNode;
|
|
47
|
+
small?: WidgetNode;
|
|
48
|
+
medium?: WidgetNode;
|
|
49
|
+
large?: WidgetNode;
|
|
50
|
+
pages?: Record<string, WidgetNode>;
|
|
51
|
+
initialPage?: string;
|
|
52
|
+
accessoryRectangular?: WidgetNode;
|
|
53
|
+
accessoryCircular?: WidgetNode;
|
|
54
|
+
accessoryInline?: WidgetNode;
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
export interface WidgetRemoteConfig {
|
|
58
|
+
url: string;
|
|
59
|
+
method?: 'GET' | 'POST';
|
|
60
|
+
headers?: Record<string, string>;
|
|
61
|
+
intervalMinutes?: number;
|
|
62
|
+
body?: Record<string, any>;
|
|
63
|
+
}
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
### Static API Methods
|
|
67
|
+
- `LiveActivity.start(options: StartActivityOptions): Promise<string>`: Starts an activity, returns `activityId`.
|
|
68
|
+
- `LiveActivity.update(options: { activityId?: string; layout?: WidgetNode; dynamicIsland?: ... }): Promise<void>`
|
|
69
|
+
- `LiveActivity.end(options: { activityId?: string; dismissalPolicy?: 'immediate'|'default' }): Promise<void>`
|
|
70
|
+
- `LiveActivity.endAll(): Promise<void>`
|
|
71
|
+
- `LiveActivity.getAllPushTokens(): Promise<{ devicePushToken: string; pushToStartToken: string; activityUpdateToken: string }>`
|
|
72
|
+
- `LiveActivity.registerActionHandler(handler: (actionId: string, payload?: any) => void): () => void`
|
|
73
|
+
- `Widget.setLayout(widgetKey: string, config: WidgetLayoutConfig, appGroup?: string): Promise<void>`
|
|
74
|
+
- `Widget.reload(widgetKey?: string): Promise<void>`
|
|
75
|
+
- `Widget.reloadAll(): Promise<void>`
|
|
76
|
+
- `Widget.setRemoteConfig(config: WidgetRemoteConfig, widgetKey?: string, appGroup?: string): Promise<void>`
|
|
77
|
+
- `Widget.requestPin(): Promise<boolean>`: Android only.
|
|
78
|
+
- `SharedStorage.setAppGroup(appGroup: string): void`
|
|
79
|
+
- `SharedStorage.set(key: string, value: string, appGroup?: string): Promise<void>`
|
|
80
|
+
- `SharedStorage.get(key: string, appGroup?: string): Promise<string | null>`
|
|
81
|
+
- `SharedStorage.remove(key: string, appGroup?: string): Promise<void>`
|
|
82
|
+
|
|
83
|
+
---
|
|
84
|
+
|
|
85
|
+
## 3. Complete Declarative UI Engine (`UI.*`)
|
|
86
|
+
|
|
87
|
+
### Container Components
|
|
88
|
+
- `UI.VStack({ spacing, padding, backgroundColor, borderRadius, alignment: 'leading'|'center'|'trailing' }, ...children)`
|
|
89
|
+
- `UI.HStack({ spacing, padding, backgroundColor, borderRadius, alignment: 'top'|'center'|'bottom' }, ...children)`
|
|
90
|
+
- `UI.ZStack({ zAlignment: 'center'|'topLeading'|'bottomTrailing' }, ...children)`
|
|
91
|
+
- `UI.Grid({ columns: number, columnSpacing: number, rowSpacing: number }, ...children)`
|
|
92
|
+
- `UI.Divider({ color, thickness, marginVertical, marginHorizontal })`
|
|
93
|
+
|
|
94
|
+
### Content & Visual Components
|
|
95
|
+
- `UI.Text(content: string, options?: { color, fontSize, fontWeight: 'regular'|'medium'|'bold'|'heavy', maxLines, textAlign })`
|
|
96
|
+
- `UI.Image(options: { url?: string, base64?: string, systemName?: string, width: number, height: number, cornerRadius?: number, contentMode?: 'fill'|'fit', tintColor?: string })`
|
|
97
|
+
- `UI.Timer(timestampMs: number, options?: { mode: 'countdown'|'timer'|'relative', color?: string, fontSize?: number, fontWeight?: string, showsHours?: boolean })`: Zero-battery native clock.
|
|
98
|
+
- `UI.Progress(options: { style?: 'bar'|'segmented'|'circular', value?: number, segments?: number, currentSegment?: number, tintColor?: string, trackColor?: string, height?: number, showPercentage?: boolean })`
|
|
99
|
+
- `UI.Equalizer(options: { isPlaying: boolean, barCount?: number, tintColor?: string, height?: number, barWidth?: number, spacing?: number })`: Animated waveform.
|
|
100
|
+
- `UI.Badge(text: string, options?: { backgroundColor, textColor, fontSize, paddingHorizontal, paddingVertical, borderRadius })`
|
|
101
|
+
- `UI.Gauge(value: number, options?: { size, tintColor, trackColor, label, valueText, textColor, labelColor })`: 240° KPI Gauge.
|
|
102
|
+
- `UI.Chart(values: number[], options?: { style: 'bar'|'line', labels?: string[], tintColor, secondaryColor, labelColor, height })`
|
|
103
|
+
|
|
104
|
+
### Interactive Components
|
|
105
|
+
- `UI.Button(options: { title: string, actionId: string, backgroundColor?: string, activeBackgroundColor?: string, color?: string, activeColor?: string, fontSize?: number, paddingHorizontal?: number, paddingVertical?: number, borderRadius?: number })`
|
|
106
|
+
- `UI.Toggle(options: { isOn: boolean, actionId: string, onColor?: string, offColor?: string })`
|
|
107
|
+
- `UI.Link(options: { deepLink: string, padding?: number, backgroundColor?: string, borderRadius?: number }, ...children)`
|
|
108
|
+
|
|
109
|
+
---
|
|
110
|
+
|
|
111
|
+
## 4. Production Architectural Guidelines
|
|
112
|
+
|
|
113
|
+
1. **App Termination (Force-Kill)**:
|
|
114
|
+
When an iOS app is terminated from the App Switcher, Hermes/JSC is killed. Widget interactions run purely in native Swift. Do not design critical flows (such as employee clock-ins or payments) expecting a TypeScript callback to fire when the app is dead. Instead, write to `SharedStorage` natively, and consume the queue upon app launch.
|
|
115
|
+
2. **Widget Budget Limits**:
|
|
116
|
+
iOS limits daily widget reloads (~40-70/day). Android Doze Mode batches periodic tasks. Use `Widget.setRemoteConfig` for general background polling, but use Server Push (APNs / FCM) for second-by-second updates.
|
|
117
|
+
3. **App Group Setup**:
|
|
118
|
+
The App Group string passed to `SharedStorage.setAppGroup('group.com.yourcompany.app')` must match the entitlement configured in Xcode and `app.json`.
|
package/docs/llms.txt
ADDED
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
# react-native-live-widgets
|
|
2
|
+
|
|
3
|
+
> The All-in-One declarative TypeScript engine for iOS Live Activities, Dynamic Island, and interactive Home Screen Widgets in React Native & Expo (iOS 16.1+ & Android 16).
|
|
4
|
+
|
|
5
|
+
Write 100% Declarative TypeScript (`UI.*`) in your React Native code. Automatically renders to native SwiftUI (WidgetKit) and Android High-DPI 2D Canvas without manually touching Xcode or Android Studio.
|
|
6
|
+
|
|
7
|
+
## Quick Reference for LLMs & AI Agents
|
|
8
|
+
|
|
9
|
+
### Core Modules
|
|
10
|
+
- `LiveActivity`: Start, update, end, and inspect lock screen Live Activities & Dynamic Island on iOS, and Promoted Live Updates (`Notification.ProgressStyle`) on Android.
|
|
11
|
+
- `Widget`: Set dynamic multi-page layouts (`pages`), configure background API polling (`setRemoteConfig`), trigger reload, and request in-app widget pinning (`requestPin` on Android).
|
|
12
|
+
- `SharedStorage`: Fast synchronous App Group (iOS) and SharedPreferences (Android) key-value bridge.
|
|
13
|
+
- `UI`: Declarative DSL builder (`UI.VStack`, `UI.HStack`, `UI.ZStack`, `UI.Text`, `UI.Button`, `UI.Progress`, `UI.Timer`, `UI.Equalizer`, `UI.Image`, `UI.Gauge`, `UI.Chart`).
|
|
14
|
+
|
|
15
|
+
### Installation & Scaffolding
|
|
16
|
+
- **Expo (SDK 50, 51, 52, 58+)**:
|
|
17
|
+
```bash
|
|
18
|
+
npx expo install react-native-live-widgets
|
|
19
|
+
# Add plugin in app.json with appGroup, enableLiveActivities
|
|
20
|
+
npx expo prebuild
|
|
21
|
+
npx react-native-live-widgets init --group group.com.yourcompany.app
|
|
22
|
+
```
|
|
23
|
+
- **Bare React Native CLI**:
|
|
24
|
+
```bash
|
|
25
|
+
npm install react-native-live-widgets
|
|
26
|
+
npx react-native-live-widgets init --group group.com.yourcompany.app
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
### Key Declarative UI DSL Methods
|
|
30
|
+
- `UI.VStack(options, ...children)` / `UI.HStack(options, ...children)`: Flex containers with `spacing`, `padding`, `backgroundColor`, `borderRadius`, `alignment`.
|
|
31
|
+
- `UI.Text(content, { color, fontSize, fontWeight: 'bold'|'heavy'|'medium'|'regular', maxLines })`
|
|
32
|
+
- `UI.Timer(timestampMs, { mode: 'countdown'|'timer'|'relative', color, fontSize })`: Zero-battery native hardware clock.
|
|
33
|
+
- `UI.Progress(options)`: Supports `style: 'bar' | 'segmented' | 'circular'`, `value` (0.0 to 1.0), `tintColor`, `trackColor`.
|
|
34
|
+
- `UI.Equalizer({ isPlaying: true, barCount: 4, tintColor, height })`: Realtime animated audio waveform on Dynamic Island & lock screen.
|
|
35
|
+
- `UI.Image({ url, base64, systemName, width, height, cornerRadius, contentMode })`: Auto-cached remote images, base64 data, or SF Symbols.
|
|
36
|
+
- `UI.Button({ title, actionId, backgroundColor, color, fontSize })`: Interactive widget button triggering `AppIntents` (iOS 17+) and `BroadcastReceiver` (Android).
|
|
37
|
+
- `UI.Gauge(value, { size, tintColor, trackColor, label, valueText })`: 240° KPI circular gauge.
|
|
38
|
+
- `UI.Chart(dataPoints, { style: 'bar'|'line', labels, tintColor, height })`: Lightweight trend sparklines.
|
|
39
|
+
|
|
40
|
+
### Bidirectional Two-Way Action Handling
|
|
41
|
+
```typescript
|
|
42
|
+
import { LiveActivity, Widget } from 'react-native-live-widgets';
|
|
43
|
+
|
|
44
|
+
// Listen to widget button interactions inside App.tsx
|
|
45
|
+
const unsubscribe = LiveActivity.registerActionHandler((actionId, payload) => {
|
|
46
|
+
if (actionId === 'INCREMENT') {
|
|
47
|
+
// Update local state and trigger widget redraw
|
|
48
|
+
Widget.reload('main');
|
|
49
|
+
}
|
|
50
|
+
});
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
### Golden Rules for AI Agents
|
|
54
|
+
1. **Never write Swift or Kotlin files manually** when a declarative `UI.*` node exists.
|
|
55
|
+
2. **App Groups**: Both iOS app and Widget Extension MUST share the identical App Group name (e.g. `group.<bundle_id>`).
|
|
56
|
+
3. **Dynamic Island**: Always configure `compactLeading`, `compactTrailing`, `minimal`, and `expanded` (`leading`, `trailing`, `bottom`, `center`).
|
|
57
|
+
4. **App Termination (Force-Kill)**: When the app is force-killed on iOS, JS runtime stops. Design mission-critical actions (like employee attendance check-ins) using native `SharedStorage` queue rather than expecting live JS callbacks while killed.
|
|
58
|
+
5. **Background Sync**: `Widget.setRemoteConfig` allows native widgets to fetch fresh JSON from a REST endpoint without requiring server-side APNs push infrastructure.
|
|
59
|
+
|
|
60
|
+
## Documentation Links
|
|
61
|
+
- [English Full Guide](https://github.com/React-Native-Vu/react-native-live-widgets/blob/dev/docs/GUIDE-EN.md)
|
|
62
|
+
- [Vietnamese Full Guide](https://github.com/React-Native-Vu/react-native-live-widgets/blob/dev/docs/GUIDE-VI.md)
|
|
63
|
+
- [Dedicated Expo Guide (EN)](https://github.com/React-Native-Vu/react-native-live-widgets/blob/dev/docs/EXPO-GUIDE-EN.md)
|
|
64
|
+
- [Dedicated Expo Guide (VI)](https://github.com/React-Native-Vu/react-native-live-widgets/blob/dev/docs/EXPO-GUIDE-VI.md)
|
|
65
|
+
- [Official Expo Demo Repo](https://github.com/React-Native-Vu/LiveWidgetsExampleExpo)
|
|
66
|
+
- [Official Bare RN Demo Repo](https://github.com/React-Native-Vu/LiveWidgetsExample)
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "react-native-live-widgets",
|
|
3
|
-
"version": "1.1.
|
|
3
|
+
"version": "1.1.1",
|
|
4
4
|
"description": "All-in-One Live Activities (iOS 16.1+ WidgetKit / Dynamic Island), Live Updates (Android 16+ ProgressStyle) and Interactive Multi-Page Home Screen Widgets for React Native & Expo with Declarative Dynamic UI Engine",
|
|
5
5
|
"main": "lib/index.js",
|
|
6
6
|
"types": "lib/index.d.ts",
|
|
@@ -39,6 +39,7 @@
|
|
|
39
39
|
"build": "node scripts/build.js",
|
|
40
40
|
"typecheck": "tsc --noEmit",
|
|
41
41
|
"prepack": "node scripts/build.js",
|
|
42
|
+
"docs:serve": "npx serve docs",
|
|
42
43
|
"version:patch": "node scripts/release.js patch",
|
|
43
44
|
"version:minor": "node scripts/release.js minor",
|
|
44
45
|
"version:major": "node scripts/release.js major",
|