react-native-live-widgets 1.0.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.
Files changed (37) hide show
  1. package/CHANGELOG.md +14 -0
  2. package/README.md +197 -49
  3. package/android/build.gradle +14 -20
  4. package/android/src/main/AndroidManifest.xml +1 -0
  5. package/android/src/main/java/com/reactnativeliveactivity/bridge/LiveActivityModule.kt +2 -1
  6. package/android/src/main/java/com/reactnativeliveactivity/liveactivity/LiveActivityHeadlessTaskService.kt +8 -0
  7. package/android/src/main/java/com/reactnativeliveactivity/liveactivity/LiveActivityReceiver.kt +4 -1
  8. package/android/src/main/java/com/reactnativeliveactivity/renderer/DynamicWidgetCanvasRenderer.kt +29 -3
  9. package/android/src/main/java/com/reactnativeliveactivity/storage/DynamicWidgetStateStore.kt +21 -0
  10. package/android/src/main/java/com/reactnativeliveactivity/widgets/DynamicHomeScreenWidgetProvider.kt +51 -15
  11. package/android/src/main/res/layout/rn_live_widget_host.xml +64 -74
  12. package/app.plugin.js +114 -0
  13. package/assets/cross_platform_parity.png +0 -0
  14. package/assets/donate_qr.png +0 -0
  15. package/assets/dynamic_island_expanded.png +0 -0
  16. package/assets/home_widget_interactive.png +0 -0
  17. package/assets/lock_screen_live_activity.png +0 -0
  18. package/cli/setup.js +445 -48
  19. package/docs/EXPO-GUIDE-EN.md +405 -0
  20. package/docs/EXPO-GUIDE-VI.md +427 -0
  21. package/docs/GUIDE-EN.md +75 -14
  22. package/docs/GUIDE-VI.md +75 -14
  23. package/docs/index.html +405 -0
  24. package/docs/llms-full.txt +118 -0
  25. package/docs/llms.txt +66 -0
  26. package/lib/builder.js +9 -13
  27. package/lib/builder.js.map +1 -1
  28. package/lib/dispatcher.js +6 -11
  29. package/lib/dispatcher.js.map +1 -1
  30. package/lib/index.d.ts.map +1 -1
  31. package/lib/index.js +40 -53
  32. package/lib/index.js.map +1 -1
  33. package/lib/types.js +1 -2
  34. package/lib/types.js.map +1 -1
  35. package/package.json +22 -4
  36. package/src/index.ts +12 -4
  37. package/src/react-native-env.d.ts +29 -0
package/docs/GUIDE-VI.md CHANGED
@@ -1,23 +1,28 @@
1
1
  # HƯỚNG DẪN SỬ DỤNG VÀ THIẾT LẬP THƯ VIỆN REACT-NATIVE-LIVE-WIDGETS 🚀
2
2
 
3
- > 🌐 **Language:** **Tiếng Việt** | [English (GUIDE-EN.md)](./GUIDE-EN.md)
3
+ > 🌐 **Language:** **Tiếng Việt** | [English (GUIDE-EN.md)](./GUIDE-EN.md) • [⚡ Hướng dẫn riêng cho Expo (EXPO-GUIDE-VI.md)](./EXPO-GUIDE-VI.md)
4
4
 
5
5
  Tài liệu hướng dẫn toàn diện từ cài đặt, thiết lập native (iOS/Android), xây dựng giao diện động bằng JavaScript/TypeScript cho cả **Live Activities (Dynamic Island / Lock Screen / Android Live Update)** và **Home Screen Widgets (Tiện ích màn hình chính tương tác đa trang)**.
6
6
 
7
+ > [!TIP]
8
+ > **Bạn đang dùng Expo (SDK 50, 51, 52, 58+)?** Hãy đọc ngay [Hướng dẫn Tích hợp Expo Chuyên sâu (EXPO-GUIDE-VI.md)](./EXPO-GUIDE-VI.md) để sử dụng Expo Config Plugin và EAS Build một cách tối ưu nhất!
9
+
7
10
  ---
8
11
 
9
12
  ## MỤC LỤC
10
13
  1. [Giới thiệu và Kiến trúc](#1-giới-thiệu-và-kiến-trúc)
11
- 2. [Cài đặt và Thiết lập Dự án](#2-cài-đặt-và-thiết-lập-dự-án)
12
- - [Cài đặt package](#cài-đặt-package)
14
+ 2. [Kho Mã Nguồn Demo Chính Thức (Expo & Bare RN)](#2-kho-mã-nguồn-demo-chính-thức-expo--bare-rn)
15
+ 3. [Cài đặt và Thiết lập Dự án](#3-cài-đặt-và-thiết-lập-dự-án)
16
+ - [Dành cho dự án Expo](#dành-cho-dự-án-expo)
17
+ - [Cài đặt package (Bare React Native)](#cài-đặt-package)
13
18
  - [Thiết lập iOS (Xcode & Widget Extension)](#thiết-lập-ios-xcode--widget-extension)
14
19
  - [Thiết lập Android (Gradle, Manifest, MainApplication & Permissions)](#thiết-lập-android-gradle-manifest-mainapplication--permissions)
15
20
  - [Cấu trúc Thư mục Native của Thư viện (`ios/` & `android/`)](#cấu-trúc-thư-mục-native-của-thư-viện-ios--android)
16
- 3. [Tài liệu API (Core API Reference)](#3-tài-liệu-api-core-api-reference)
21
+ 4. [Tài liệu API (Core API Reference)](#4-tài-liệu-api-core-api-reference)
17
22
  - [LiveActivity API (Màn hình khóa, Dynamic Island & 3 loại Push Token)](#1-liveactivity-api)
18
23
  - [Widget API (Tiện ích màn hình chính, Multi-page & Background Sync)](#2-widget-api)
19
24
  - [SharedStorage API (Đồng bộ App Groups & SharedPreferences)](#3-sharedstorage-api)
20
- 4. [Xây dựng Giao diện Động (Declarative UI Engine)](#4-xây-dựng-giao-diện-động-declarative-ui-engine)
25
+ 5. [Xây dựng Giao diện Động (Declarative UI Engine)](#5-xây-dựng-giao-diện-động-declarative-ui-engine)
21
26
  - [UI.VStack & UI.HStack](#uivstack--uihstack)
22
27
  - [UI.Text](#uitext)
23
28
  - [UI.Timer (Realtime không tốn pin)](#uitimer-realtime-không-tốn-pin)
@@ -25,15 +30,15 @@ Tài liệu hướng dẫn toàn diện từ cài đặt, thiết lập native (
25
30
  - [UI.Equalizer (Sóng nhạc chuyển động liên tục)](#uiequalizer-sóng-nhạc-chuyển-động-liên-tục)
26
31
  - [UI.Image (URL mạng, Base64, File, Asset & SF Symbols)](#uiimage-url-mạng-base64-file-asset--sf-symbols)
27
32
  - [UI.Button (Tương tác chuyển trang, Tick công việc, Refresh API & Deep Link)](#uibutton-nút-bấm-tương-tác-trực-tiếp-trên-widget)
28
- 5. [Cấu hình Dynamic Island (iPhone 14 Pro, 15, 16, 17)](#5-cấu-hình-dynamic-island-iphone-14-pro-15-16-17)
29
- 6. [Tạo Home Screen & Lock Screen Widget Đa Dạng bằng JavaScript](#6-tạo-home-screen-widget-đa-trang--tương-tác-bằng-javascript)
33
+ 6. [Cấu hình Dynamic Island (iPhone 14 Pro, 15, 16, 17)](#6-cấu-hình-dynamic-island-iphone-14-pro-15-16-17)
34
+ 7. [Tạo Home Screen & Lock Screen Widget Đa Dạng bằng JavaScript](#7-tạo-home-screen-widget-đa-trang--tương-tác-bằng-javascript)
30
35
  - [Lock Screen Widgets trên iOS (accessoryRectangular, circular, inline)](#lock-screen-widgets-trên-ios)
31
36
  - [Ghim Tiện ích vào Màn hình chính trong App (Android In-App Pin)](#ghim-tiện-ích-vào-màn-hình-chính-trong-app-android-in-app-pin)
32
- 7. [Đồng bộ API Ngầm cho Widget kể cả khi Kill App (`Widget.setRemoteConfig`)](#7-đồng-bộ-api-ngầm-cho-widget-kể-cả-khi-kill-app-widgetsetremoteconfig)
33
- 8. [Quản lý 3 loại Push Token (APNs & FCM) cho Live Activity](#8-quản-lý-3-loại-push-token-apns--fcm-cho-live-activity)
34
- 9. [State Machine & Tự động cập nhật theo pha (Phases)](#9-state-machine--tự-động-cập-nhật-theo-pha-phases)
35
- 10. [Cấu trúc Payload Server Push (APNs & FCM)](#10-cấu-trúc-payload-server-push-apns--fcm)
36
- 11. [Xử lý sự cố thường gặp (Troubleshooting)](#11-xử-lý-sự-cố-thường-gặp-troubleshooting)
37
+ 8. [Đồng bộ API Ngầm cho Widget kể cả khi Kill App (`Widget.setRemoteConfig`)](#8-đồng-bộ-api-ngầm-cho-widget-kể-cả-khi-kill-app-widgetsetremoteconfig)
38
+ 9. [Quản lý 3 loại Push Token (APNs & FCM) cho Live Activity](#9-quản-lý-3-loại-push-token-apns--fcm-cho-live-activity)
39
+ 10. [State Machine & Tự động cập nhật theo pha (Phases)](#10-state-machine--tự-động-cập-nhật-theo-pha-phases)
40
+ 11. [Cấu trúc Payload Server Push (APNs & FCM)](#11-cấu-trúc-payload-server-push-apns--fcm)
41
+ 12. [Xử lý sự cố thường gặp (Troubleshooting)](#12-xử-lý-sự-cố-thường-gặp-troubleshooting)
37
42
 
38
43
  ---
39
44
 
@@ -48,9 +53,47 @@ Thư viện **`react-native-live-widgets`** là giải pháp All-in-One cho phé
48
53
 
49
54
  ---
50
55
 
51
- ## 2. Cài đặt và Thiết lập Dự án
56
+ ## 2. Kho Mã Nguồn Demo Chính Thức (Expo & Bare RN)
57
+
58
+ Để xem cách thức triển khai thực tế và chạy thử nghiệm ngay lập tức, bạn có thể tham khảo 2 kho mã nguồn mẫu chính thức:
59
+
60
+ | Nền tảng | Kho mã nguồn (GitHub) | Đặc điểm nổi bật |
61
+ | :--- | :--- | :--- |
62
+ | **🚀 Expo (SDK 58 / CNG)** | 👉 **[https://github.com/React-Native-Vu/LiveWidgetsExampleExpo](https://github.com/React-Native-Vu/LiveWidgetsExampleExpo)** | Tích hợp Continuous Native Generation bằng Expo Config Plugin (`app.plugin.js`), không cần đụng mã Swift/Kotlin. |
63
+ | **⚛️ Bare React Native CLI** | 👉 **[https://github.com/React-Native-Vu/LiveWidgetsExample](https://github.com/React-Native-Vu/LiveWidgetsExample)** | Dành cho dự án thuần React Native CLI với cấu hình Xcode Extension và Android Studio hoàn chỉnh. |
64
+
65
+ ### ⚡ Chạy Nhanh Demo Expo (LiveWidgetsExampleExpo):
66
+ ```bash
67
+ git clone https://github.com/React-Native-Vu/LiveWidgetsExampleExpo.git
68
+ cd LiveWidgetsExampleExpo
69
+ npm install
70
+ npx expo prebuild
71
+ npm run setup:widgets
72
+ npx expo run:ios # hoặc npx expo run:android
73
+ ```
74
+
75
+ ---
76
+
77
+ ## 3. Cài đặt và Thiết lập Dự án
78
+
79
+ ### Dành cho dự án Expo
80
+ Nếu bạn sử dụng **Expo**, thư viện hỗ trợ sẵn **Expo Config Plugin (`app.plugin.js`)** và **CLI Wizard**.
81
+ 👉 **Xem hướng dẫn chi tiết từng bước tại: [Tài liệu Expo Tích hợp (EXPO-GUIDE-VI.md)](./EXPO-GUIDE-VI.md)**
82
+
83
+ ```bash
84
+ # 1. Cài đặt
85
+ npx expo install react-native-live-widgets
52
86
 
53
- ### Cài đặt package
87
+ # 2. Thêm plugin vào app.json và sinh mã native
88
+ npx expo prebuild
89
+
90
+ # 3. Tự động liên kết target Widget Extension
91
+ npx react-native-live-widgets init --group group.com.yourcompany.app
92
+ ```
93
+
94
+ ---
95
+
96
+ ### Cài đặt package (Dành cho Bare React Native CLI)
54
97
  Trong thư mục gốc của dự án React Native:
55
98
  ```bash
56
99
  npm install react-native-live-widgets
@@ -459,6 +502,12 @@ UI.Button({
459
502
  })
460
503
  ```
461
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
+
462
511
  ### `UI.ZStack`, `UI.Grid` & `UI.Divider` (Bố cục nâng cao)
463
512
  ```typescript
464
513
  // 1. ZStack: Xếp chồng các lớp (Overlay)
@@ -568,6 +617,11 @@ UI.Custom('WeatherCard', { city: 'TP.HCM', temp: '31°C' })
568
617
 
569
618
  ## 5. Cấu hình Dynamic Island (iPhone 14 Pro, 15, 16, 17)
570
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
+
571
625
  ```typescript
572
626
  dynamicIsland: {
573
627
  compactLeading: UI.HStack(
@@ -708,6 +762,13 @@ await Widget.setRemoteConfig({
708
762
  - Trên **Android**: `AlarmManager` tự động đánh thức `LiveActivityReceiver` (`ACTION_WIDGET_SYNC`), tải JSON mới và vẽ lại `DynamicHomeScreenWidgetProvider`.
709
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`).
710
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
+
711
772
  ---
712
773
 
713
774
  ## 8. Quản lý 3 loại Push Token (APNs & FCM) cho Live Activity
@@ -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>