react-native-live-widgets 1.1.0 → 1.2.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.
- package/CHANGELOG.md +20 -0
- package/README.md +76 -10
- package/android/build.gradle +14 -20
- package/android/src/main/AndroidManifest.xml +1 -0
- package/android/src/main/java/com/reactnativeliveactivity/bridge/LiveActivityModule.kt +5 -1
- 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 +26 -1
- 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 +109 -7
- package/docs/GUIDE-VI.md +109 -7
- package/docs/index.html +440 -0
- package/docs/llms-full.txt +132 -0
- package/docs/llms.txt +88 -0
- package/ios/Models/DynamicLayoutModels.swift +5 -0
- package/ios/Widgets/DynamicHomeScreenWidget.swift +2 -3
- package/lib/builder.d.ts.map +1 -1
- package/lib/builder.js +29 -19
- package/lib/builder.js.map +1 -1
- package/lib/dispatcher.d.ts +7 -0
- package/lib/dispatcher.d.ts.map +1 -1
- package/lib/dispatcher.js +11 -0
- package/lib/dispatcher.js.map +1 -1
- package/lib/hooks.d.ts +66 -0
- package/lib/hooks.d.ts.map +1 -0
- package/lib/hooks.js +166 -0
- package/lib/hooks.js.map +1 -0
- package/lib/index.d.ts +32 -7
- package/lib/index.d.ts.map +1 -1
- package/lib/index.js +115 -8
- package/lib/index.js.map +1 -1
- package/lib/jsx.d.ts +79 -0
- package/lib/jsx.d.ts.map +1 -0
- package/lib/jsx.js +196 -0
- package/lib/jsx.js.map +1 -0
- package/lib/preview.d.ts +54 -0
- package/lib/preview.d.ts.map +1 -0
- package/lib/preview.js +466 -0
- package/lib/preview.js.map +1 -0
- package/lib/types.d.ts +8 -0
- package/lib/types.d.ts.map +1 -1
- package/package.json +3 -1
- package/src/builder.ts +29 -19
- package/src/dispatcher.ts +17 -0
- package/src/hooks.ts +223 -0
- package/src/index.ts +137 -13
- package/src/jsx.tsx +296 -0
- package/src/preview.tsx +719 -0
- package/src/react-ambient.d.ts +10 -0
- package/src/react-native-env.d.ts +43 -0
- package/src/types.ts +8 -0
package/docs/index.html
ADDED
|
@@ -0,0 +1,440 @@
|
|
|
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
|
+
// Cách 1: Dùng React Hook (Khuyến nghị - An toàn tuyệt đối với Fast Refresh)
|
|
320
|
+
useWidgetAction('INCREMENT', () => {
|
|
321
|
+
setCounter(c => c + 1);
|
|
322
|
+
});
|
|
323
|
+
|
|
324
|
+
// Cách 2: Lắng nghe toàn cục Imperative
|
|
325
|
+
Widget.onWidgetAction((actionId) => {
|
|
326
|
+
if (actionId === 'INCREMENT') {
|
|
327
|
+
setCounter(c => c + 1);
|
|
328
|
+
}
|
|
329
|
+
});</code></pre>
|
|
330
|
+
</div>
|
|
331
|
+
|
|
332
|
+
<!-- Card: JSX Syntax & In-App Widget Preview -->
|
|
333
|
+
<div class="bg-cardBg border border-cardBorder rounded-xl p-4 space-y-3">
|
|
334
|
+
<div class="flex items-center justify-between">
|
|
335
|
+
<span class="text-sm font-semibold text-white">✨ Cú pháp JSX / TSX & Xem Trước Widget Trong App (<WidgetPreview>)</span>
|
|
336
|
+
<span class="text-xs text-sky-400 bg-sky-500/10 px-2 py-0.5 rounded">v1.2.0 JSX</span>
|
|
337
|
+
</div>
|
|
338
|
+
<pre><code class="language-typescript">import { WidgetPreview, VStack, HStack, Text, Badge, Button } from 'react-native-live-widgets';
|
|
339
|
+
|
|
340
|
+
// 1. Nhúng khung xem trước trực tiếp trên màn hình App (hỗ trợ small, medium, large)
|
|
341
|
+
<WidgetPreview size="medium" showBadge interactiveSizeSwitch onAction={(id) => alert(id)}>
|
|
342
|
+
<VStack padding={16} backgroundColor="#0F172A" borderRadius={16}>
|
|
343
|
+
<HStack justifyContent="spaceBetween">
|
|
344
|
+
<Text fontSize={14} fontWeight="bold" color="#FFFFFF">Ca làm sáng</Text>
|
|
345
|
+
<Badge text="07:54 (Hợp lệ)" backgroundColor="#064E3B" textColor="#6EE7B7" />
|
|
346
|
+
</HStack>
|
|
347
|
+
<Button title="Làm mới dữ liệu" actionId="refresh" fullWidth />
|
|
348
|
+
</VStack>
|
|
349
|
+
</WidgetPreview>
|
|
350
|
+
|
|
351
|
+
// 2. Cập nhật Widget ra Home Screen bằng JSX trực tiếp:
|
|
352
|
+
await Widget.setLayout('main', {
|
|
353
|
+
medium: (
|
|
354
|
+
<VStack padding={16} backgroundColor="#0F172A" borderRadius={16}>
|
|
355
|
+
<Text fontSize={14} color="#FFF">Xin chào Trần Tuấn Vũ</Text>
|
|
356
|
+
<Button title="Check-in" actionId="checkin" />
|
|
357
|
+
</VStack>
|
|
358
|
+
)
|
|
359
|
+
});</code></pre>
|
|
360
|
+
</div>
|
|
361
|
+
</div>
|
|
362
|
+
</section>
|
|
363
|
+
|
|
364
|
+
<!-- Section: AI Agent & LLM Hub -->
|
|
365
|
+
<section id="llms-ai" class="space-y-6 pt-4 border-t border-cardBorder">
|
|
366
|
+
<div class="flex items-center space-x-3">
|
|
367
|
+
<div class="p-2 rounded-lg bg-indigo-500/10 border border-indigo-500/20 text-indigo-400">
|
|
368
|
+
<i data-lucide="bot" class="w-6 h-6"></i>
|
|
369
|
+
</div>
|
|
370
|
+
<div>
|
|
371
|
+
<h2 class="text-2xl sm:text-3xl font-bold text-white">AI Agent & LLM Hub (llms.txt)</h2>
|
|
372
|
+
<p class="text-sm text-slate-400">Tối ưu 100% cho các mô hình AI: ChatGPT, Claude, Copilot, Cursor, Antigravity</p>
|
|
373
|
+
</div>
|
|
374
|
+
</div>
|
|
375
|
+
|
|
376
|
+
<p class="text-slate-300">
|
|
377
|
+
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>,
|
|
378
|
+
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).
|
|
379
|
+
</p>
|
|
380
|
+
|
|
381
|
+
<div class="grid grid-cols-1 md:grid-cols-2 gap-4">
|
|
382
|
+
<div class="bg-cardBg border border-indigo-900/40 rounded-xl p-5 space-y-3">
|
|
383
|
+
<div class="flex items-center justify-between">
|
|
384
|
+
<span class="font-bold text-white flex items-center space-x-2">
|
|
385
|
+
<i data-lucide="file-text" class="w-4 h-4 text-indigo-400"></i>
|
|
386
|
+
<span>Tập tin llms.txt</span>
|
|
387
|
+
</span>
|
|
388
|
+
<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">
|
|
389
|
+
Xem file raw ↗
|
|
390
|
+
</a>
|
|
391
|
+
</div>
|
|
392
|
+
<p class="text-xs text-slate-400">
|
|
393
|
+
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.
|
|
394
|
+
</p>
|
|
395
|
+
<pre><code class="language-bash">curl -s https://react-native-vu.github.io/react-native-live-widgets/llms.txt</code></pre>
|
|
396
|
+
</div>
|
|
397
|
+
|
|
398
|
+
<div id="agent-skill" class="bg-cardBg border border-indigo-900/40 rounded-xl p-5 space-y-3">
|
|
399
|
+
<div class="flex items-center justify-between">
|
|
400
|
+
<span class="font-bold text-white flex items-center space-x-2">
|
|
401
|
+
<i data-lucide="cpu" class="w-4 h-4 text-sky-400"></i>
|
|
402
|
+
<span>Agent Skill (SKILL.md)</span>
|
|
403
|
+
</span>
|
|
404
|
+
<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">
|
|
405
|
+
Xem SKILL.md ↗
|
|
406
|
+
</a>
|
|
407
|
+
</div>
|
|
408
|
+
<p class="text-xs text-slate-400">
|
|
409
|
+
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.
|
|
410
|
+
</p>
|
|
411
|
+
<pre><code class="language-bash"># Vị trí skill trong dự án của bạn
|
|
412
|
+
.agents/skills/react-native-live-widgets/SKILL.md</code></pre>
|
|
413
|
+
</div>
|
|
414
|
+
</div>
|
|
415
|
+
</section>
|
|
416
|
+
|
|
417
|
+
</main>
|
|
418
|
+
</div>
|
|
419
|
+
|
|
420
|
+
<!-- Footer -->
|
|
421
|
+
<footer class="border-t border-cardBorder bg-cardBg/50 py-8 mt-16">
|
|
422
|
+
<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">
|
|
423
|
+
<div>
|
|
424
|
+
Phát triển bởi <strong class="text-white">vu-tran</strong> • Giấy phép MIT •
|
|
425
|
+
<a href="https://github.com/React-Native-Vu/react-native-live-widgets" class="text-sky-400 hover:underline">GitHub Repository</a>
|
|
426
|
+
</div>
|
|
427
|
+
<div class="flex items-center space-x-4">
|
|
428
|
+
<a href="llms.txt" class="hover:text-white transition">llms.txt</a>
|
|
429
|
+
<a href="llms-full.txt" class="hover:text-white transition">llms-full.txt</a>
|
|
430
|
+
<a href="EXPO-GUIDE-VI.md" class="hover:text-white transition">Expo Guide</a>
|
|
431
|
+
</div>
|
|
432
|
+
</div>
|
|
433
|
+
</footer>
|
|
434
|
+
|
|
435
|
+
<script>
|
|
436
|
+
// Initialize Lucide icons
|
|
437
|
+
lucide.createIcons();
|
|
438
|
+
</script>
|
|
439
|
+
</body>
|
|
440
|
+
</html>
|
|
@@ -0,0 +1,132 @@
|
|
|
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<boolean>`
|
|
71
|
+
- `LiveActivity.getAllPushTokens(activityId?: string): Promise<LiveActivityPushTokens>`
|
|
72
|
+
- `LiveActivity.registerAction(actionId: string, handler: ActionHandler): () => void`
|
|
73
|
+
- `LiveActivity.registerActionHandler(handler: (actionId: string, payload?: any) => void): () => void`
|
|
74
|
+
- `Widget.setLayout(widgetKey: string, config: WidgetLayoutConfig, appGroup?: string): Promise<boolean>` (alias: `Widget.update`)
|
|
75
|
+
- `Widget.reload(widgetKey?: string): Promise<boolean>`
|
|
76
|
+
- `Widget.reloadAll(): Promise<boolean>`
|
|
77
|
+
- `Widget.setRemoteConfig(widgetKey: string, config: WidgetRemoteConfig, appGroup?: string): Promise<boolean>` (supports shorthand `Widget.setRemoteConfig(config, appGroup?)`)
|
|
78
|
+
- `Widget.onWidgetAction(handler: (actionId: string, payload?: any) => void): () => void`
|
|
79
|
+
- `Widget.requestPin(): Promise<boolean>`: Android only.
|
|
80
|
+
|
|
81
|
+
### React Hooks (Fast Refresh Resilient)
|
|
82
|
+
- `useWidgetAction(actionIdOrCallback: string | ((actionId: string, payload?: any) => void), handler?: ActionHandler): void`
|
|
83
|
+
- `useLiveActivity(initialActivityId?: string): UseLiveActivityResult`
|
|
84
|
+
- `useWidgetState<T>(key: string, initialValue: T, appGroup?: string): [T, (val: T | ((prev: T) => T)) => Promise<void>, () => Promise<void>]`
|
|
85
|
+
|
|
86
|
+
### In-App Widget Preview Component
|
|
87
|
+
- `<WidgetPreview size="small"|"medium"|"large"|"lockScreen" layout={node} showBadge interactiveSizeSwitch onAction={(actionId) => ...} />` (alias: `<VoltraWidgetPreview>`)
|
|
88
|
+
|
|
89
|
+
### Dual UI Authoring Syntax
|
|
90
|
+
- **JSX Components**: `<VStack>`, `<HStack>`, `<ZStack>`, `<Grid>`, `<Text>`, `<Button>`, `<Badge>`, `<Progress>`, `<Timer>`, `<Image>`, `<Spacer>`, `<Divider>`, `<Link>`, `<Equalizer>`, `<Gauge>`, `<Chart>`. Fully supports `style` props, StyleSheet objects, and conditional style arrays!
|
|
91
|
+
- **Functional DSL**: `UI.VStack(...)`, `UI.HStack(...)`, `UI.Text(...)`, `UI.Button(...)`, etc.
|
|
92
|
+
- `SharedStorage.setAppGroup(appGroup: string): void`
|
|
93
|
+
- `SharedStorage.set(key: string, value: string, appGroup?: string): Promise<void>`
|
|
94
|
+
- `SharedStorage.get(key: string, appGroup?: string): Promise<string | null>`
|
|
95
|
+
- `SharedStorage.remove(key: string, appGroup?: string): Promise<void>`
|
|
96
|
+
|
|
97
|
+
---
|
|
98
|
+
|
|
99
|
+
## 3. Complete Declarative UI Engine (`UI.*`)
|
|
100
|
+
|
|
101
|
+
### Container Components
|
|
102
|
+
- `UI.VStack({ spacing, padding, backgroundColor, borderRadius, alignment: 'leading'|'center'|'trailing' }, ...children)`
|
|
103
|
+
- `UI.HStack({ spacing, padding, backgroundColor, borderRadius, alignment: 'top'|'center'|'bottom' }, ...children)`
|
|
104
|
+
- `UI.ZStack({ zAlignment: 'center'|'topLeading'|'bottomTrailing' }, ...children)`
|
|
105
|
+
- `UI.Grid({ columns: number, columnSpacing: number, rowSpacing: number }, ...children)`
|
|
106
|
+
- `UI.Divider({ color, thickness, marginVertical, marginHorizontal })`
|
|
107
|
+
|
|
108
|
+
### Content & Visual Components
|
|
109
|
+
- `UI.Text(content: string, options?: { color, fontSize, fontWeight: 'regular'|'medium'|'bold'|'heavy', maxLines, textAlign })`
|
|
110
|
+
- `UI.Image(options: { url?: string, base64?: string, systemName?: string, width: number, height: number, cornerRadius?: number, contentMode?: 'fill'|'fit', tintColor?: string })`
|
|
111
|
+
- `UI.Timer(timestampMs: number, options?: { mode: 'countdown'|'timer'|'relative', color?: string, fontSize?: number, fontWeight?: string, showsHours?: boolean })`: Zero-battery native clock.
|
|
112
|
+
- `UI.Progress(options: { style?: 'bar'|'segmented'|'circular', value?: number, segments?: number, currentSegment?: number, tintColor?: string, trackColor?: string, height?: number, showPercentage?: boolean })`
|
|
113
|
+
- `UI.Equalizer(options: { isPlaying: boolean, barCount?: number, tintColor?: string, height?: number, barWidth?: number, spacing?: number })`: Animated waveform.
|
|
114
|
+
- `UI.Badge(text: string, options?: { backgroundColor, textColor, fontSize, paddingHorizontal, paddingVertical, borderRadius })`
|
|
115
|
+
- `UI.Gauge(value: number, options?: { size, tintColor, trackColor, label, valueText, textColor, labelColor })`: 240° KPI Gauge.
|
|
116
|
+
- `UI.Chart(values: number[], options?: { style: 'bar'|'line', labels?: string[], tintColor, secondaryColor, labelColor, height })`
|
|
117
|
+
|
|
118
|
+
### Interactive Components
|
|
119
|
+
- `UI.Button(options: { title: string, actionId: string, backgroundColor?: string, activeBackgroundColor?: string, color?: string, activeColor?: string, fontSize?: number, paddingHorizontal?: number, paddingVertical?: number, borderRadius?: number })`
|
|
120
|
+
- `UI.Toggle(options: { isOn: boolean, actionId: string, onColor?: string, offColor?: string })`
|
|
121
|
+
- `UI.Link(options: { deepLink: string, padding?: number, backgroundColor?: string, borderRadius?: number }, ...children)`
|
|
122
|
+
|
|
123
|
+
---
|
|
124
|
+
|
|
125
|
+
## 4. Production Architectural Guidelines
|
|
126
|
+
|
|
127
|
+
1. **App Termination (Force-Kill)**:
|
|
128
|
+
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.
|
|
129
|
+
2. **Widget Budget Limits**:
|
|
130
|
+
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.
|
|
131
|
+
3. **App Group Setup**:
|
|
132
|
+
The App Group string passed to `SharedStorage.setAppGroup('group.com.yourcompany.app')` must match the entitlement configured in Xcode and `app.json`.
|