react-native-live-widgets 1.2.1 → 1.2.3

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 (79) hide show
  1. package/CHANGELOG.md +37 -0
  2. package/README.md +89 -49
  3. package/android/src/main/AndroidManifest.xml +12 -0
  4. package/android/src/main/assets/fonts/MaterialIcons-Regular.ttf +0 -0
  5. package/android/src/main/java/com/reactnativeliveactivity/bridge/LiveActivityModule.kt +61 -1
  6. package/android/src/main/java/com/reactnativeliveactivity/liveactivity/LiveActivityNotifier.kt +153 -17
  7. package/android/src/main/java/com/reactnativeliveactivity/liveactivity/LiveActivityReceiver.kt +1 -1
  8. package/android/src/main/java/com/reactnativeliveactivity/renderer/DynamicWidgetCanvasRenderer.kt +86 -13
  9. package/android/src/main/java/com/reactnativeliveactivity/storage/DynamicWidgetImageCache.kt +53 -0
  10. package/android/src/main/java/com/reactnativeliveactivity/storage/DynamicWidgetStateStore.kt +647 -104
  11. package/android/src/main/java/com/reactnativeliveactivity/widgets/DynamicHomeScreenWidgetProvider.kt +3 -1
  12. package/android/src/main/java/com/reactnativeliveactivity/widgets/DynamicQuickSettingsTileService.kt +120 -0
  13. package/app.plugin.js +36 -0
  14. package/assets/MaterialIcons.json +2236 -0
  15. package/cli/codegen.js +889 -0
  16. package/cli/setup.js +323 -63
  17. package/docs/EXPO-GUIDE-EN.md +21 -3
  18. package/docs/EXPO-GUIDE-VI.md +21 -3
  19. package/docs/GUIDE-EN.md +203 -21
  20. package/docs/GUIDE-VI.md +207 -22
  21. package/docs/index.html +1461 -226
  22. package/docs/llms-full.txt +15 -0
  23. package/docs/llms.txt +16 -7
  24. package/ios/Bridge/LiveActivityModule.swift +333 -44
  25. package/ios/Intents/DynamicWidgetActionIntent.swift +57 -2
  26. package/ios/Models/DynamicLayoutModels.swift +114 -4
  27. package/ios/Renderer/DynamicNodeView.swift +15 -6
  28. package/ios/Storage/DynamicWidgetStateStore.swift +649 -38
  29. package/ios/Widgets/DynamicControlWidget.swift +63 -0
  30. package/ios/Widgets/DynamicHomeScreenWidget.swift +99 -26
  31. package/ios/Widgets/DynamicLiveActivityWidget.swift +25 -4
  32. package/lib/builder.d.ts +50 -7
  33. package/lib/builder.d.ts.map +1 -1
  34. package/lib/builder.js +326 -18
  35. package/lib/builder.js.map +1 -1
  36. package/lib/hooks.d.ts +13 -9
  37. package/lib/hooks.d.ts.map +1 -1
  38. package/lib/hooks.js +70 -12
  39. package/lib/hooks.js.map +1 -1
  40. package/lib/index.d.ts +80 -7
  41. package/lib/index.d.ts.map +1 -1
  42. package/lib/index.js +303 -59
  43. package/lib/index.js.map +1 -1
  44. package/lib/ir.d.ts.map +1 -1
  45. package/lib/ir.js +9 -2
  46. package/lib/ir.js.map +1 -1
  47. package/lib/jsx.d.ts +11 -7
  48. package/lib/jsx.d.ts.map +1 -1
  49. package/lib/jsx.js +50 -13
  50. package/lib/jsx.js.map +1 -1
  51. package/lib/material-icons.generated.d.ts +8 -0
  52. package/lib/material-icons.generated.d.ts.map +1 -0
  53. package/lib/material-icons.generated.js +9 -0
  54. package/lib/material-icons.generated.js.map +1 -0
  55. package/lib/preview.d.ts +11 -4
  56. package/lib/preview.d.ts.map +1 -1
  57. package/lib/preview.js +150 -82
  58. package/lib/preview.js.map +1 -1
  59. package/lib/sf-symbols.generated.d.ts +8 -0
  60. package/lib/sf-symbols.generated.d.ts.map +1 -0
  61. package/lib/sf-symbols.generated.js +9 -0
  62. package/lib/sf-symbols.generated.js.map +1 -0
  63. package/lib/types.d.ts +302 -18
  64. package/lib/types.d.ts.map +1 -1
  65. package/package.json +6 -2
  66. package/scripts/build.js +98 -0
  67. package/scripts/generate-material-icons.js +93 -0
  68. package/scripts/generate-sf-symbols.js +95 -0
  69. package/scripts/release.js +115 -0
  70. package/scripts/test-ir-semantic.js +314 -0
  71. package/src/builder.ts +382 -24
  72. package/src/hooks.ts +88 -12
  73. package/src/index.ts +319 -56
  74. package/src/ir.ts +8 -2
  75. package/src/jsx.tsx +69 -21
  76. package/src/material-icons.generated.ts +3844 -0
  77. package/src/preview.tsx +235 -81
  78. package/src/sf-symbols.generated.ts +9533 -0
  79. package/src/types.ts +348 -18
@@ -1,6 +1,6 @@
1
1
  # HƯỚNG DẪN TÍCH HỢP VÀ SỬ DỤNG EXPO VỚI REACT-NATIVE-LIVE-WIDGETS 🚀
2
2
 
3
- > 🌐 **Language:** **Tiếng Việt** | [English Guide (EXPO-GUIDE-EN.md)](./EXPO-GUIDE-EN.md) • [📖 Bare RN Guide (GUIDE-VI.md)](./GUIDE-VI.md) • [⚡ Kho mã nguồn mẫu Expo](https://github.com/React-Native-Vu/LiveWidgetsExampleExpo)
3
+ > 🌐 **Language:** **Tiếng Việt** | [English Guide (EXPO-GUIDE-EN.md)](./EXPO-GUIDE-EN.md) • [📖 Bare RN Guide (GUIDE-VI.md)](./GUIDE-VI.md) • [⚡ Kho mã nguồn mẫu Expo](https://github.com/React-Native-Vu/LiveWidgetsExampleExpo) • [🌐 Web Docs (Live Simulator)](https://react-native-vu.github.io/react-native-live-widgets/)
4
4
 
5
5
  Tài liệu này hướng dẫn chi tiết cách tích hợp **`react-native-live-widgets`** vào ứng dụng **Expo (SDK 50, 51, 52, 58+)**, từ cấu hình Expo Config Plugin, thiết lập iOS WidgetKit/ActivityKit tự động, chạy trên Local Simulator bằng Expo Dev Client cho đến việc đóng gói phát hành qua **EAS Build**.
6
6
 
@@ -86,7 +86,25 @@ npx expo run:android
86
86
 
87
87
  ## 3. Cài đặt & Thiết lập Từng bước
88
88
 
89
- ### Bước 1: Cài đặt package
89
+ ### Cách nhanh nhất: Tự động hoá 100% bằng 1 câu lệnh
90
+
91
+ ```bash
92
+ # 1. Cài đặt package
93
+ npx expo install react-native-live-widgets
94
+
95
+ # 2. Khởi tạo tự động (Tự chèn Config Plugin vào app.json, tạo widgets.config.ts, sync icons & Swift)
96
+ npx react-native-live-widgets init
97
+
98
+ # 3. Chạy ứng dụng trên máy ảo / thiết bị thật
99
+ npx expo run:ios
100
+ # hoặc: npx expo run:android
101
+ ```
102
+
103
+ ---
104
+
105
+ ### Quy trình thủ công (Nếu bạn muốn tự kiểm soát cấu hình)
106
+
107
+ #### Bước 1: Cài đặt package
90
108
  Tại thư mục gốc của dự án Expo:
91
109
  ```bash
92
110
  npx expo install react-native-live-widgets
@@ -94,7 +112,7 @@ npx expo install react-native-live-widgets
94
112
 
95
113
  ---
96
114
 
97
- ### Bước 2: Cấu hình `app.json` (Expo Config Plugin)
115
+ #### Bước 2: Cấu hình `app.json` (Expo Config Plugin)
98
116
  Mở file `app.json` và bổ sung plugin `react-native-live-widgets`:
99
117
 
100
118
  ```json
package/docs/GUIDE-EN.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # REACT-NATIVE-LIVE-WIDGETS — COMPLETE SETUP & DEVELOPER GUIDE 🚀
2
2
 
3
- > 🌐 **Language:** [Tiếng Việt (GUIDE-VI.md)](./GUIDE-VI.md) | **English** • [⚡ Dedicated Expo Guide (EXPO-GUIDE-EN.md)](./EXPO-GUIDE-EN.md)
3
+ > 🌐 **Language:** [Tiếng Việt (GUIDE-VI.md)](./GUIDE-VI.md) | **English** • [⚡ Dedicated Expo Guide (EXPO-GUIDE-EN.md)](./EXPO-GUIDE-EN.md) • [🌐 Web Docs & Live Simulator](https://react-native-vu.github.io/react-native-live-widgets/)
4
4
 
5
5
  Comprehensive guide covering installation, native setup (iOS & Android), and building 100% JavaScript/TypeScript declarative layouts for **Live Activities (Dynamic Island / Lock Screen / Android Live Updates)** and **Interactive Multi-Page Home Screen Widgets**.
6
6
 
@@ -37,8 +37,10 @@ Comprehensive guide covering installation, native setup (iOS & Android), and bui
37
37
  8. [Background API Auto-Sync When App Is Killed (`Widget.setRemoteConfig`)](#8-background-api-auto-sync-when-app-is-killed-widgetsetremoteconfig)
38
38
  9. [Managing All 3 Push Token Types (APNs & FCM)](#9-managing-all-3-push-token-types-apns--fcm)
39
39
  10. [State Machine & Timed Phases (`phases`)](#10-state-machine--timed-phases-phases)
40
- 11. [Server Push Payload Structure (APNs & FCM)](#11-server-push-payload-structure-apns--fcm)
41
- 12. [Troubleshooting](#12-troubleshooting)
40
+ 11. [Server Push Payload Structure (APNs & FCM)](#10-server-push-payload-structure-apns--fcm)
41
+ 12. [Troubleshooting](#11-troubleshooting)
42
+ 13. [Advanced Styling Modifiers, UI IR, Exact Hit Layer & Platform Matrix (v1.2.1)](#12-advanced-styling-modifiers--platform-capability-matrix)
43
+ 14. [TypeScript-Driven Swift Codegen & Automated i18n Sync (`widgets.config.ts`)](#14-typescript-driven-swift-codegen--automated-i18n-sync-widgetsconfigts)
42
44
 
43
45
  ---
44
46
 
@@ -76,32 +78,47 @@ npx expo run:ios # or npx expo run:android
76
78
 
77
79
  ## 3. Installation & Project Setup
78
80
 
79
- ### For Expo Projects
80
- If you are using **Expo**, the library provides an **Expo Config Plugin (`app.plugin.js`)** and **CLI Wizard** out of the box.
81
- 👉 **See the dedicated step-by-step guide: [Expo Integration Guide (EXPO-GUIDE-EN.md)](./EXPO-GUIDE-EN.md)**
81
+ ### 📋 CLI Command Cheat Sheet
82
+
83
+ | Command | Purpose | When to use |
84
+ | :--- | :--- | :--- |
85
+ | `npx react-native-live-widgets init` | **All-in-One Automated Setup**: Configures `app.json` (Expo), Xcode Extension target, Entitlements, App Groups, Podfile, `pod install`, Android permissions, default `widgets.config.ts`, SF Symbols/Material Icons sync, and Swift bundle codegen. | First time setting up the library in your project |
86
+ | `npx react-native-live-widgets codegen` | **Sync & Re-generate**: Re-reads `widgets.config.ts` and syncs `LiveWidgetsBundle.swift`, iOS `Localizable.xcstrings`, Android `strings.xml`, and type definitions. | Whenever you edit `widgets.config.ts` or add new widgets/locales |
87
+ | `npx react-native-live-widgets init --group <name>` | **Custom App Group**: Explicitly specify your App Group identifier (e.g. `group.com.mycompany.app`). | If you prefer a custom group instead of auto-detection |
88
+
89
+ ---
90
+
91
+ ### Option A: For Expo Projects (Managed / CNG)
82
92
 
83
93
  ```bash
84
94
  # 1. Install package
85
95
  npx expo install react-native-live-widgets
86
96
 
87
- # 2. Add plugin to app.json & generate native projects
88
- npx expo prebuild
97
+ # 2. Automated one-command setup (updates app.json, creates widgets.config.ts, syncs icons & bundle)
98
+ npx react-native-live-widgets init
89
99
 
90
- # 3. Automatically link and configure Widget Extension
91
- npx react-native-live-widgets init --group group.com.yourcompany.app
100
+ # 3. Launch on Simulator / Emulator
101
+ npx expo run:ios
102
+ # or: npx expo run:android
92
103
  ```
93
104
 
105
+ > 👉 **See the dedicated step-by-step guide: [Expo Integration Guide (EXPO-GUIDE-EN.md)](./EXPO-GUIDE-EN.md)**
106
+
94
107
  ---
95
108
 
96
- ### Package Installation (Bare React Native CLI)
97
- From the root directory of your React Native project:
109
+ ### Option B: For Bare React Native CLI
110
+
98
111
  ```bash
112
+ # 1. Install package
99
113
  npm install react-native-live-widgets
100
- # or
101
- yarn add react-native-live-widgets
114
+ # or: yarn add react-native-live-widgets
115
+
116
+ # 2. Automated one-command setup (links Xcode target, Podfile, pod install, Android permissions, widgets.config.ts, codegen)
117
+ npx react-native-live-widgets init
102
118
 
103
- # Automatically configure Info.plist, Entitlements, AndroidManifest & Widget templates
104
- npx react-native-live-widgets init --group group.com.yourcompany.app
119
+ # 3. Launch on Simulator / Emulator
120
+ npx react-native run-ios
121
+ # or: npx react-native run-android
105
122
  ```
106
123
 
107
124
  ---
@@ -536,15 +553,38 @@ UI.Image({
536
553
  cornerRadius: 8,
537
554
  })
538
555
 
539
- // 3. System Icon (SF Symbols on iOS / Vector Mapping on Android)
556
+ // 3. Cross-Platform System Icons (Apple SF Symbols + Google Material Icons)
557
+ // Option A: Automatically mapped on both platforms
540
558
  UI.Image({
541
- systemName: 'bicycle',
542
- tintColor: '#FB923C',
543
- width: 18,
544
- height: 18,
559
+ systemName: 'bolt',
560
+ tintColor: '#10B981',
561
+ width: 20,
562
+ height: 20,
563
+ })
564
+
565
+ // Option B: Explicitly specify platform-dedicated icons (with 9,500+ SF Symbols & 3,800+ Material Icons Auto-Complete types)
566
+ UI.Image({
567
+ systemNameIos: 'bolt.horizontal.fill', // 9,500+ Apple SF Symbols
568
+ systemNameAndroid: 'bolt', // 3,800+ Google Material Icons (supports snake_case and kebab-case)
569
+ tintColor: '#10B981',
570
+ width: 24,
571
+ height: 24,
545
572
  })
573
+
574
+ // Or using React JSX Component syntax:
575
+ <Image
576
+ systemNameIos="person.crop.circle.badge.checkmark"
577
+ systemNameAndroid="verified_user"
578
+ tintColor="#10B981"
579
+ width={24}
580
+ height={24}
581
+ />
546
582
  ```
547
583
 
584
+ > 💡 **Official Icon Catalogs & Galleriy Links:**
585
+ > - 🍏 **Apple SF Symbols (9,500+ Icons)**: Browse and preview symbols at [Apple SF Symbols Official Website](https://developer.apple.com/sf-symbols/). Fully typed via `KnownSFSymbol` auto-complete.
586
+ > - 🤖 **Google Material Icons (3,800+ Icons)**: Browse icon names at [Google Fonts Icons / Material Symbols](https://fonts.google.com/icons). Fully typed via `KnownMaterialIcon`, supporting both `snake_case` (e.g. `battery_charging_full`) and `kebab-case` (`battery-charging-full`).
587
+
548
588
  ### `UI.Button` (Interactive Widget Buttons)
549
589
  Lets users interact directly on the Widget surface (via iOS 17+ `AppIntents` and Android `PendingIntent` hit zones) **without opening the app**:
550
590
  ```typescript
@@ -1185,6 +1225,148 @@ Version **v1.2.1** addresses critical real-world interaction challenges on physi
1185
1225
 
1186
1226
  ---
1187
1227
 
1228
+ ### 12.8. 📱 Extended Widget Families (`extraLarge`, `standBy`, `ControlWidget`) & Complete Live Activity Lifecycle
1229
+
1230
+ #### 1. Extended Widget Families
1231
+ Beyond `small`, `medium`, `large`, and Lock Screen (`accessoryRectangular`, `accessoryCircular`, `accessoryInline`) layouts:
1232
+ - **`extraLarge?: LayoutNode`**: Targets iPadOS (`systemExtraLarge`) and Android tablets (`widgetHeightDp >= 280dp`). Supported in `<WidgetPreview size="extraLarge">`.
1233
+ - **`standBy?: LayoutNode`**: Automatically activated in iOS 17+ StandBy Mode (`family == .systemSmall && !showsWidgetContainerBackground`), alongside `.applyStandByMargins()` and `widgetAccentable` support on `Text`, `Progress`, `Gauge`, and `Image`. Supported in `<WidgetPreview size="standBy">`.
1234
+ - **iOS 18+ Control Widgets & Android Quick Settings Tile (`ControlWidget` / `Widget.setControl`)**: Configure iOS 18 Control Center, Lock Screen controls, and Action Button widgets natively via `ios/Widgets/DynamicControlWidget.swift` (`DynamicControlWidget` & `DynamicControlToggleWidget`) and Android Quick Settings Tiles via `DynamicQuickSettingsTileService.kt`, connected directly to `DynamicWidgetStateStore` and `useWidgetAction`:
1235
+ ```typescript
1236
+ import { ControlWidget, UI, WidgetPreview } from 'react-native-live-widgets';
1237
+
1238
+ const shiftControl = ControlWidget.toggle({
1239
+ title: 'Work Shift',
1240
+ subtitle: 'Tap to clock in',
1241
+ checkedTitle: 'On Shift',
1242
+ checkedSubtitle: 'Tap to clock out',
1243
+ systemName: 'clock.badge.checkmark.fill',
1244
+ checked: true,
1245
+ actionId: 'toggle:attendance',
1246
+ });
1247
+
1248
+ await ControlWidget.set('toggle', shiftControl);
1249
+ // Also supports UI.ControlButton({ ... }) and Widget.setControl('main', ...)
1250
+ // Preview in-app: <WidgetPreview size="control" controlConfig={shiftControl} />
1251
+ ```
1252
+
1253
+ #### 2. Complete Live Activity Lifecycle API
1254
+ - **Multi-Activity Management**: `LiveActivity.getActiveActivities()`, `LiveActivity.get(activityId)`, `LiveActivity.isActive(activityId)`, and `LiveActivity.endAll()` return user-assigned `activityId`, `systemActivityId`, state flags, and tokens.
1255
+ - **Stale State (`staleTimestamp`, `staleLockScreen`, `staleDynamicIsland`)**: Automatically transitions UI to fallback views when stale (`context.isStale` on iOS 16.2+ / timestamp check on Android).
1256
+ - **Relevance Score (`relevanceScore`)**: Prioritizes ordering in Dynamic Island / Lock Screen (`ActivityContent.relevanceScore`) and Android Notification Shade (`setSortKey`).
1257
+ - **Alert Configuration (`alertConfig`)**: Supports `{ title, body, sound }` via iOS 16.2+ `AlertConfiguration` and Android notification alerts on updates.
1258
+ - **Scheduled End & Auto-Expiration (`scheduledEndTimestamp`, `autoEndAfterSeconds`, `expiredLockScreen`, `expiredDismissalPolicy`)**: Automatically updates or dismisses activities on expiration, plus `LiveActivity.cleanupExpired()` and `LiveActivity.onStateChange((ev) => ...)` emitting `'active' | 'started_by_push' | 'stale' | 'expired' | 'ended' | 'dismissed'`.
1259
+ - **Upgraded `useLiveActivity()` Hook**: Exposes `activities`, `lifecycleState`, `isStale`, `refreshActivities`, and `cleanupExpired`.
1260
+
1261
+ ---
1262
+
1263
+ ### 12.9. 🔄 Background Data Engine 2.0 & Structured Data Binding
1264
+
1265
+ `Widget.setRemoteConfig` and `Widget.createDataBinding<T>()` provide a complete native background data engine on both iOS WidgetKit Extension and Android even after the main app is force-killed:
1266
+
1267
+ | Category | Native Capabilities (iOS SwiftUI + Android) |
1268
+ | :--- | :--- |
1269
+ | **REST & Auth** | `url`, `method` (`GET`/`POST`/`PUT`), JSON `body`, custom `headers`, and **`authRefresh`** (automatically refreshes tokens on HTTP `401` and retries) |
1270
+ | **Network & Cache** | **`cacheTtlSeconds`** to avoid redundant fetches across timeline reloads, **`enableETag`** (`If-None-Match`/`If-Modified-Since` + HTTP `304 Not Modified`), **`timeoutMs`**, and **`maxRetries` + `retryDelayMs`** (Exponential Backoff) |
1271
+ | **Multi-Source & Transform** | **`sources`** to fetch & namespace multiple APIs (`<sourceKey>.<nested.path>`), recursive JSON Flattener (`user.name`, `items.0.title`), declarative **`mapping`**, and **`schema`** validation (`requiredKeys`, `types`, `defaults`) |
1272
+ | **Error State** | System tokens `{{_syncStatus}}` (`ok` / `partial` / `error`), `{{_syncError}}`, `{{_httpStatus}}`, plus **`errorFallback`** `LayoutNode` while preserving valid cached data on failures |
1273
+ | **Structured Data Binding** | `Widget.createDataBinding<T>()` & `UI.bind(path, pipes)` supporting nested paths & Native Pipes (`default`, `divide`, `multiply`, `add`, `round`, `upper`, `lower`, `currency`, `percent`, `if`) |
1274
+
1275
+ ```tsx
1276
+ const data = Widget.createDataBinding<{
1277
+ user: { name: string };
1278
+ attendance: { progress: number };
1279
+ }>({
1280
+ defaults: { user: { name: 'Employee' }, attendance: { progress: 0 } },
1281
+ });
1282
+
1283
+ await Widget.setLayout('main', {
1284
+ medium: (
1285
+ <VStack padding={14} spacing={6}>
1286
+ <Text>{data.user.name}</Text>
1287
+ <Text>{data.attendance.progress}%</Text>
1288
+ <Progress value={data.attendance.progress.divide(100)} />
1289
+ </VStack>
1290
+ ),
1291
+ });
1292
+
1293
+ await Widget.setRemoteConfig('main', {
1294
+ cacheTtlSeconds: 300,
1295
+ timeoutMs: 6000,
1296
+ enableETag: true,
1297
+ maxRetries: 2,
1298
+ retryDelayMs: 500,
1299
+ sources: {
1300
+ user: { url: 'https://api.yourapp.com/me' },
1301
+ attendance: { url: 'https://api.yourapp.com/attendance/today' },
1302
+ },
1303
+ schema: { requiredKeys: ['user.name', 'attendance.progress'], types: { 'attendance.progress': 'number' } },
1304
+ authRefresh: { url: 'https://api.yourapp.com/auth/refresh', method: 'POST', tokenPath: 'accessToken' },
1305
+ errorFallback: <Text color="#F87171">Sync error ({{_httpStatus}}): {{_syncError}}</Text>,
1306
+ refreshIntervalMinutes: 15,
1307
+ });
1308
+ ```
1309
+
1310
+ > ⚠️ **Important OS Reload Budget Disclaimer:** Exact 15-minute background intervals are **not guaranteed** when the app is terminated. **Apple WidgetKit** enforces a dynamic daily reload budget (typically ~**40–70 reloads/day** depending on user engagement; `refreshIntervalMinutes` maps to `TimelineReloadPolicy.after(...)` as an earliest hint, not an exact cron guarantee). **Android** likewise enforces Doze Mode and App Standby Buckets. For real-time second-by-second updates, pair widgets with server pushes (APNs / FCM).
1311
+
1312
+ ---
1313
+
1314
+ ## 14. TypeScript-Driven Swift Codegen & Automated i18n Sync (`widgets.config.ts`)
1315
+
1316
+ Starting from version 1.2.1, you don't need to manually modify Swift bundle source files (`LiveWidgetsBundle.swift`) or configure localization files in Xcode. The entire configuration is defined in **100% TypeScript** via `widgets.config.ts` in your project root.
1317
+
1318
+ ### 1. Sample `widgets.config.ts`:
1319
+ ```typescript
1320
+ import { defineWidgetConfig } from 'react-native-live-widgets';
1321
+
1322
+ export default defineWidgetConfig({
1323
+ bundleName: 'LiveWidgetsBundle',
1324
+ liveActivity: true, // Enable/disable Live Activity Widget
1325
+ controlWidgets: true, // Enable Control Center Widget (iOS 18+)
1326
+ defaultLocale: 'en',
1327
+ locales: {
1328
+ en: {
1329
+ 'widgets.main.title': 'Live Widgets Utility',
1330
+ 'widgets.main.desc': 'Visual KPI and attendance tracking',
1331
+ },
1332
+ vi: {
1333
+ 'widgets.main.title': 'Tiện ích Live Widgets',
1334
+ 'widgets.main.desc': 'Theo dõi KPI và chấm công trực quan',
1335
+ },
1336
+ },
1337
+ widgets: [
1338
+ {
1339
+ key: 'main',
1340
+ kind: 'LiveWidget_main',
1341
+ displayName: 'widgets.main.title',
1342
+ description: 'widgets.main.desc',
1343
+ supportedFamilies: ['systemSmall', 'systemMedium', 'systemLarge'],
1344
+ },
1345
+ ],
1346
+ });
1347
+ ```
1348
+
1349
+ ### 2. Execute Codegen CLI:
1350
+ ```bash
1351
+ npx react-native-live-widgets codegen
1352
+ ```
1353
+
1354
+ This CLI command automatically:
1355
+ 1. **Syncs System Icons**: Automatically extracts **9,500+ Apple SF Symbols** from macOS and **3,800+ Google Material Icons** into auto-complete type definition files (`sf-symbols.generated.ts` & `material-icons.generated.ts`), providing full TypeScript IntelliSense.
1356
+ 2. **Generates Swift Source Bundle**: Creates `ios/LiveWidgetsExtension/LiveWidgetsBundle.swift` registering all configured Widgets and Control Center widgets.
1357
+ 3. **Synchronizes iOS Localization**: Generates modern Apple String Catalog `ios/LiveWidgetsExtension/Localizable.xcstrings` for all defined languages.
1358
+ 4. **Synchronizes Android Localization**: Automatically updates `android/app/src/main/res/values/strings.xml` (default locale) and `values-{lang}/strings.xml` for Android AppWidget localized names.
1359
+
1360
+ ---
1361
+
1362
+ ### 🌐 Online Interactive Web Documentation
1363
+
1364
+ - **Web Documentation & Live Simulator**: [https://react-native-vu.github.io/react-native-live-widgets/](https://react-native-vu.github.io/react-native-live-widgets/)
1365
+ - **AI Agent Quick Reference (`llms.txt`)**: [https://react-native-vu.github.io/react-native-live-widgets/llms.txt](https://react-native-vu.github.io/react-native-live-widgets/llms.txt)
1366
+ - **AI Agent Full Manual (`llms-full.txt`)**: [https://react-native-vu.github.io/react-native-live-widgets/llms-full.txt](https://react-native-vu.github.io/react-native-live-widgets/llms-full.txt)
1367
+
1368
+ ---
1369
+
1188
1370
  ## 📄 License
1189
1371
  MIT © vu-tran
1190
1372
 
package/docs/GUIDE-VI.md CHANGED
@@ -1,6 +1,6 @@
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) • [⚡ Hướng dẫn riêng cho Expo (EXPO-GUIDE-VI.md)](./EXPO-GUIDE-VI.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) • [🌐 Web Docs & Live Simulator](https://react-native-vu.github.io/react-native-live-widgets/)
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
 
@@ -37,8 +37,10 @@ Tài liệu hướng dẫn toàn diện từ cài đặt, thiết lập native (
37
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
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
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)
40
+ 11. [Cấu trúc Payload Server Push (APNs & FCM)](#10-cấu-trúc-payload-server-push-apns--fcm)
41
+ 12. [Xử lý sự cố thường gặp (Troubleshooting)](#11-xử-lý-sự-cố-thường-gặp-troubleshooting)
42
+ 13. [Hệ thống Styling Modifiers, UI IR, Exact Hit Layer & Năng lực Nền tảng (v1.2.1)](#12-hệ-thống-styling-modifiers--bảng-năng-lực-nền-tảng-capability--fallback-matrix)
43
+ 14. [TypeScript-Driven Swift Codegen & Tự động Đồng bộ Đa ngôn ngữ i18n (`widgets.config.ts`)](#14-typescript-driven-swift-codegen--tự-động-đồng-bộ-đa-ngôn-ngữ-i18n-widgetsconfigts)
42
44
 
43
45
  ---
44
46
 
@@ -76,32 +78,47 @@ npx expo run:ios # hoặc npx expo run:android
76
78
 
77
79
  ## 3. Cài đặt và Thiết lập Dự án
78
80
 
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)**
81
+ ### 📋 Bảng Tra Cứu Các Lệnh CLI Quan Trọng
82
+
83
+ | Lệnh | Chức năng | Thời điểm sử dụng |
84
+ | :--- | :--- | :--- |
85
+ | `npx react-native-live-widgets init` | **Thiết lập tự động All-in-One**: Tự cấu hình `app.json` (Expo), Xcode Target, Entitlements, Podfile, `pod install`, Android permissions, tạo file `widgets.config.ts`, trích xuất 13,000+ icons và biên dịch Swift bundle. | Chạy 1 lần duy nhất khi tích hợp thư viện vào dự án |
86
+ | `npx react-native-live-widgets codegen` | **Đồng bộ Codegen & i18n**: Đọc lại `widgets.config.ts`, cập nhật `LiveWidgetsBundle.swift`, Apple String Catalog (`Localizable.xcstrings`) và Android `strings.xml`. | Mỗi khi sửa `widgets.config.ts` hoặc thêm widget/ngôn ngữ mới |
87
+ | `npx react-native-live-widgets init --group <name>` | **Chỉ định App Group tuỳ chỉnh**: Ví dụ `group.com.yourcompany.app`. | Khi bạn muốn dùng App Group khác với mã bundle tự nhận diện |
88
+
89
+ ---
90
+
91
+ ### Cách 1: Dành cho dự án Expo (Managed / CNG)
82
92
 
83
93
  ```bash
84
- # 1. Cài đặt
94
+ # Bước 1: Cài đặt thư viện
85
95
  npx expo install react-native-live-widgets
86
96
 
87
- # 2. Thêm plugin vào app.json và sinh mã native
88
- npx expo prebuild
97
+ # Bước 2: Thiết lập tự động 1 lệnh (tự ghi app.json, tạo widgets.config.ts, sync icons & Swift)
98
+ npx react-native-live-widgets init
89
99
 
90
- # 3. Tự động liên kết target Widget Extension
91
- npx react-native-live-widgets init --group group.com.yourcompany.app
100
+ # Bước 3: Khởi chạy trên thiết bị / máy ảo
101
+ npx expo run:ios
102
+ # hoặc: npx expo run:android
92
103
  ```
93
104
 
105
+ > 👉 **Xem hướng dẫn chi tiết từng bước cho Expo tại: [Tài liệu Expo Tích hợp (EXPO-GUIDE-VI.md)](./EXPO-GUIDE-VI.md)**
106
+
94
107
  ---
95
108
 
96
- ### Cài đặt package (Dành cho Bare React Native CLI)
97
- Trong thư mục gốc của dự án React Native:
109
+ ### Cách 2: Dành cho Bare React Native CLI
110
+
98
111
  ```bash
112
+ # Bước 1: Cài đặt thư viện
99
113
  npm install react-native-live-widgets
100
- # hoặc
101
- yarn add react-native-live-widgets
114
+ # hoặc: yarn add react-native-live-widgets
115
+
116
+ # Bước 2: Thiết lập tự động 1 lệnh (tự cấu hình Xcode target, Podfile, pod install, Android permissions, widgets.config.ts, Swift bundle)
117
+ npx react-native-live-widgets init
102
118
 
103
- # Tự động cấu hình Info.plist, Entitlements, AndroidManifest và tạo file mẫu Widget
104
- npx react-native-live-widgets init --group group.com.yourcompany.app
119
+ # Bước 3: Khởi chạy trên thiết bị / máy ảo
120
+ npx react-native run-ios
121
+ # hoặc: npx react-native run-android
105
122
  ```
106
123
 
107
124
  ---
@@ -536,15 +553,38 @@ UI.Image({
536
553
  cornerRadius: 8,
537
554
  })
538
555
 
539
- // 3. Icon hệ thống (SF Symbols trên iOS / Vector Mapping trên Android)
556
+ // 3. Icon hệ thống đa nền tảng (Apple SF Symbols + Google Material Icons)
557
+ // Cách 1: Tự động ánh xạ trên cả 2 nền tảng
540
558
  UI.Image({
541
- systemName: 'bicycle',
542
- tintColor: '#FB923C',
543
- width: 18,
544
- height: 18,
559
+ systemName: 'bolt',
560
+ tintColor: '#10B981',
561
+ width: 20,
562
+ height: 20,
563
+ })
564
+
565
+ // Cách 2: Chỉ định icon chuyên biệt cho từng hệ điều hành (với gợi ý Type Auto-Complete 9500+ SF Symbols & 3800+ Material Icons)
566
+ UI.Image({
567
+ systemNameIos: 'bolt.horizontal.fill', // 9,500+ Apple SF Symbols chuẩn xịn
568
+ systemNameAndroid: 'bolt', // 3,800+ Google Material Icons (hỗ trợ cả snake_case và kebab-case)
569
+ tintColor: '#10B981',
570
+ width: 24,
571
+ height: 24,
545
572
  })
573
+
574
+ // Hoặc sử dụng dạng JSX React Component:
575
+ <Image
576
+ systemNameIos="person.crop.circle.badge.checkmark"
577
+ systemNameAndroid="verified_user"
578
+ tintColor="#10B981"
579
+ width={24}
580
+ height={24}
581
+ />
546
582
  ```
547
583
 
584
+ > 💡 **Tra cứu danh mục Icons chính thức từ Apple & Google:**
585
+ > - 🍏 **Apple SF Symbols (9,500+ Icons)**: Tra cứu và xem trước tại [Apple SF Symbols Official Website](https://developer.apple.com/sf-symbols/). Định nghĩa sẵn type `KnownSFSymbol` với IntelliSense auto-complete.
586
+ > - 🤖 **Google Material Icons (3,800+ Icons)**: Tra cứu tên icon tại [Google Fonts Icons / Material Symbols](https://fonts.google.com/icons). Định nghĩa sẵn type `KnownMaterialIcon`, hỗ trợ cả `snake_case` (ví dụ `battery_charging_full`) và `kebab-case` (`battery-charging-full`).
587
+
548
588
  ### `UI.Button` (Nút bấm tương tác trực tiếp trên Widget)
549
589
  Cho phép người dùng thao tác ngay trên mặt Widget (iOS 17+ `AppIntents` & Android `PendingIntent` Hit Zones) mà **không cần mở ứng dụng**:
550
590
  ```typescript
@@ -1209,5 +1249,150 @@ Phiên bản **v1.2.1** giải quyết dứt điểm các bài toán thực tế
1209
1249
 
1210
1250
  ---
1211
1251
 
1252
+ ### 12.8. 📱 Widget Family Mở rộng (`extraLarge`, `standBy`, `ControlWidget`) & Quản lý Vòng đời Live Activity Hoàn chỉnh
1253
+
1254
+ #### 1. Widget Family Mở rộng
1255
+ Ngoài 3 kích thước cơ bản (`small`, `medium`, `large`) và 3 kiểu Lock Screen (`accessoryRectangular`, `accessoryCircular`, `accessoryInline`), thư viện hỗ trợ thêm:
1256
+ - **`extraLarge?: LayoutNode`**: Dành cho iPadOS (`systemExtraLarge`) và Tablet/Android 4x4+ (`widgetHeightDp >= 280dp`). Hỗ trợ xem trước trực tiếp trong `<WidgetPreview size="extraLarge">`.
1257
+ - **`standBy?: LayoutNode`**: Tự động kích hoạt khi iPhone ở chế độ StandBy iOS 17+ (`family == .systemSmall && !showsWidgetContainerBackground`). Hỗ trợ `widgetAccentable` trên `Text`, `Progress`, `Gauge`, `Image` và `<WidgetPreview size="standBy">`. Widget extension có thể gọi `.applyStandByMargins()` trên `StaticConfiguration` để bật chế độ full-bleed.
1258
+ - **`ControlWidget` iOS 18+ & Android Quick Settings Tile (`ControlWidget` / `Widget.setControl`)**: Điều khiển trực tiếp iOS 18 Control Center, Action Button, Lock Screen Controls thông qua module [`ios/Widgets/DynamicControlWidget.swift`](https://github.com/React-Native-Vu/react-native-live-widgets/blob/dev/ios/Widgets/DynamicControlWidget.swift) (`DynamicControlWidget` & `DynamicControlToggleWidget`) và Android Quick Settings Tile qua `DynamicQuickSettingsTileService.kt` — kết nối trực tiếp vào `DynamicWidgetStateStore` và `useWidgetAction`:
1259
+ ```typescript
1260
+ import { ControlWidget, UI, WidgetPreview } from 'react-native-live-widgets';
1261
+
1262
+ const shiftControl = ControlWidget.toggle({
1263
+ title: 'Ca làm việc',
1264
+ subtitle: 'Chạm để chấm công',
1265
+ checkedTitle: 'Đang trong ca',
1266
+ checkedSubtitle: 'Nhấn để kết thúc',
1267
+ systemName: 'clock.badge.checkmark.fill',
1268
+ checked: true,
1269
+ actionId: 'toggle:attendance',
1270
+ });
1271
+
1272
+ await ControlWidget.set('toggle', shiftControl);
1273
+ // Hoặc dùng UI.ControlButton({ ... }) / Widget.setControl('main', ...)
1274
+
1275
+ // Xem trước trực tiếp trong App:
1276
+ // <WidgetPreview size="control" controlConfig={shiftControl} />
1277
+ ```
1278
+
1279
+ #### 2. API Quản lý Vòng đời Live Activity Hoàn chỉnh
1280
+ Thư viện chuẩn hóa đầy đủ 8 khả năng quản lý vòng đời cho cả iOS ActivityKit và Android Live Updates:
1281
+ - **Quản lý nhiều phiên đồng thời**: `LiveActivity.getActiveActivities()`, `LiveActivity.get(activityId)`, `LiveActivity.isActive(activityId)`, `LiveActivity.endAll()` — trả về `activityId` chính xác kèm `systemActivityId` và `pushToken`.
1282
+ - **Stale State (`staleTimestamp`, `staleLockScreen`, `staleDynamicIsland`)**: Tự động chuyển sang giao diện dự phòng khi hết độ tươi (`context.isStale` trên iOS 16.2+ / `now >= staleTimestamp` trên Android).
1283
+ - **Relevance Score (`relevanceScore`)**: Ưu tiên thứ tự hiển thị trên Lock Screen / Dynamic Island (iOS `ActivityContent.relevanceScore`) và sắp xếp ưu tiên trên Notification Shade Android (`setSortKey`).
1284
+ - **Alert Configuration (`alertConfig`)**: Hỗ trợ `{ title, body, sound }` (bên cạnh `alertTitle`/`alertBody`) qua `AlertConfiguration` khi gọi `LiveActivity.update()` trên iOS 16.2+ và bật chuông/rung trên Android.
1285
+ - **Scheduled End & Tự động xử lý hết hạn (`scheduledEndTimestamp`, `autoEndAfterSeconds`, `expiredLockScreen`, `expiredDismissalPolicy`)**: Tự động chuyển sang giao diện hết hạn hoặc đóng Activity đúng giờ hẹn, kèm `LiveActivity.cleanupExpired()` và sự kiện `LiveActivity.onStateChange((ev) => ...)` theo dõi các trạng thái `'active' | 'started_by_push' | 'stale' | 'expired' | 'ended' | 'dismissed'`.
1286
+ - **Hook `useLiveActivity` nâng cấp**: Trả về thêm `activities`, `lifecycleState`, `isStale`, `refreshActivities`, và `cleanupExpired`.
1287
+
1288
+ ---
1289
+
1290
+ ### 12.9. 🔄 Background Data Engine 2.0 & Structured Data Binding
1291
+
1292
+ `Widget.setRemoteConfig` và `Widget.createDataBinding<T>()` cung cấp động cơ đồng bộ dữ liệu nền hoàn chỉnh ngay cả khi người dùng đã vuốt đóng (Force-Kill) ứng dụng chính:
1293
+
1294
+ | Nhóm tính năng | Khả năng hỗ trợ Native (iOS SwiftUI + Android) |
1295
+ | :--- | :--- |
1296
+ | **REST & Auth** | `url`, `method` (`GET`/`POST`/`PUT`), `body` JSON, `headers` tùy biến, **`authRefresh`** tự động lấy Access Token mới khi gặp HTTP `401` |
1297
+ | **Mạng & Cache** | **`cacheTtlSeconds`** chống gọi lặp khi OS reload timeline, **`enableETag`** (`If-None-Match`/`If-Modified-Since` + HTTP `304 Not Modified`), **`timeoutMs`**, **`maxRetries` + `retryDelayMs`** (Exponential Backoff) |
1298
+ | **Đa nguồn & Chuẩn hóa** | **`sources`** gom nhiều API theo tiền tố `<sourceKey>.<nested.path>`, JSON Flattener lồng nhau (`user.name`, `items.0.title`), **`mapping`** & **`schema`** validation (`requiredKeys`, `types`, `defaults`) |
1299
+ | **Error State** | Biến hệ thống `{{_syncStatus}}` (`ok` / `partial` / `error`), `{{_syncError}}`, `{{_httpStatus}}` và **`errorFallback`** LayoutNode dự phòng (giữ nguyên dữ liệu cache hợp lệ khi mạng lỗi) |
1300
+ | **Structured Data Binding** | `Widget.createDataBinding<T>()` & `UI.bind(path, pipes)` hỗ trợ nested path & Pipe Transform (`default`, `divide`, `multiply`, `add`, `round`, `upper`, `lower`, `currency`, `percent`, `if`) |
1301
+
1302
+ ```tsx
1303
+ const data = Widget.createDataBinding<{
1304
+ user: { name: string };
1305
+ attendance: { progress: number };
1306
+ }>({
1307
+ defaults: { user: { name: 'Nhân viên' }, attendance: { progress: 0 } },
1308
+ });
1309
+
1310
+ await Widget.setLayout('main', {
1311
+ medium: (
1312
+ <VStack padding={14} spacing={6}>
1313
+ <Text>{data.user.name}</Text>
1314
+ <Text>{data.attendance.progress}%</Text>
1315
+ <Progress value={data.attendance.progress.divide(100)} />
1316
+ </VStack>
1317
+ ),
1318
+ });
1319
+
1320
+ await Widget.setRemoteConfig('main', {
1321
+ cacheTtlSeconds: 300,
1322
+ timeoutMs: 6000,
1323
+ enableETag: true,
1324
+ maxRetries: 2,
1325
+ retryDelayMs: 500,
1326
+ sources: {
1327
+ user: { url: 'https://api.yourapp.com/me' },
1328
+ attendance: { url: 'https://api.yourapp.com/attendance/today' },
1329
+ },
1330
+ schema: { requiredKeys: ['user.name', 'attendance.progress'], types: { 'attendance.progress': 'number' } },
1331
+ authRefresh: { url: 'https://api.yourapp.com/auth/refresh', method: 'POST', tokenPath: 'accessToken' },
1332
+ errorFallback: <Text color="#F87171">Lỗi đồng bộ ({{_httpStatus}}): {{_syncError}}</Text>,
1333
+ refreshIntervalMinutes: 15,
1334
+ });
1335
+ ```
1336
+
1337
+ > ⚠️ **Lưu ý quan trọng về Ngân sách Reload của Hệ điều hành:** Không cam kết đồng bộ chính xác từng 15 phút khi ứng dụng bị đóng. **Apple WidgetKit** cấp phát ngân sách reload động cho mỗi Widget (thường khoảng **40–70 lần/ngày** tùy mức độ người dùng xem/tương tác; `refreshIntervalMinutes` map sang `TimelineReloadPolicy.after(...)` như mốc thời gian *sớm nhất được đề xuất*, không phải cron timer tuyệt đối). Trên **Android**, Doze Mode và App Standby Buckets có thể gom hoặc trì hoãn tác vụ nền. Với dữ liệu cần tức thì từng giây (giao hàng, tỷ số), hãy kết hợp Push APNs / FCM.
1338
+
1339
+ ---
1340
+
1341
+ ## 14. TypeScript-Driven Swift Codegen & Tự động Đồng bộ Đa ngôn ngữ i18n (`widgets.config.ts`)
1342
+
1343
+ Từ phiên bản 1.2.1, bạn không cần phải tự tay chỉnh sửa file Swift (`LiveWidgetsBundle.swift`) hay cấu hình thủ công các file dịch `Localizable.strings` trong Xcode. Toàn bộ cấu hình được định nghĩa bằng **100% TypeScript** qua file `widgets.config.ts` ở thư mục gốc của dự án.
1344
+
1345
+ ### 1. Cấu hình `widgets.config.ts` mẫu:
1346
+ ```typescript
1347
+ import { defineWidgetConfig } from 'react-native-live-widgets';
1348
+
1349
+ export default defineWidgetConfig({
1350
+ bundleName: 'LiveWidgetsBundle',
1351
+ liveActivity: true, // Bật/tắt Widget Live Activity
1352
+ controlWidgets: true, // Bật Control Center Widget (iOS 18+)
1353
+ defaultLocale: 'vi',
1354
+ locales: {
1355
+ vi: {
1356
+ 'widgets.main.title': 'Tiện ích Live Widgets',
1357
+ 'widgets.main.desc': 'Theo dõi KPI và chấm công trực quan',
1358
+ },
1359
+ en: {
1360
+ 'widgets.main.title': 'Live Widgets Utility',
1361
+ 'widgets.main.desc': 'Visual KPI and attendance tracking',
1362
+ },
1363
+ },
1364
+ widgets: [
1365
+ {
1366
+ key: 'main',
1367
+ kind: 'LiveWidget_main',
1368
+ displayName: 'widgets.main.title',
1369
+ description: 'widgets.main.desc',
1370
+ supportedFamilies: ['systemSmall', 'systemMedium', 'systemLarge'],
1371
+ },
1372
+ ],
1373
+ });
1374
+ ```
1375
+
1376
+ ### 2. Thực thi lệnh CLI Codegen:
1377
+ ```bash
1378
+ npx react-native-live-widgets codegen
1379
+ ```
1380
+
1381
+ Lệnh này sẽ tự động:
1382
+ 1. **Trích xuất Icons hệ thống**: Tự động lấy hơn **9,500+ Apple SF Symbols** từ hệ thống macOS và hơn **3,800+ Google Material Icons** vào các file type definitions (`sf-symbols.generated.ts` & `material-icons.generated.ts`) giúp lập trình viên có IntelliSense auto-complete đầy đủ.
1383
+ 2. **Sinh mã nguồn Swift**: Tạo file `ios/LiveWidgetsExtension/LiveWidgetsBundle.swift` đăng ký đầy đủ các Widget và Control Center Widgets tự động.
1384
+ 3. **Đồng bộ đa ngôn ngữ iOS**: Tạo file String Catalog hiện đại `ios/LiveWidgetsExtension/Localizable.xcstrings` với đầy đủ các ngôn ngữ đã cấu hình.
1385
+ 4. **Đồng bộ đa ngôn ngữ Android**: Tự động ghi và cập nhật các file `android/app/src/main/res/values/strings.xml` (ngôn ngữ mặc định) và `values-{lang}/strings.xml` cho Android AppWidget.
1386
+
1387
+ ---
1388
+
1389
+ ### 🌐 Trang Web Tài Liệu Trực Tuyến & Live Simulator
1390
+
1391
+ - **Interactive Web Documentation**: [https://react-native-vu.github.io/react-native-live-widgets/](https://react-native-vu.github.io/react-native-live-widgets/)
1392
+ - **AI Agent Quick Reference (`llms.txt`)**: [https://react-native-vu.github.io/react-native-live-widgets/llms.txt](https://react-native-vu.github.io/react-native-live-widgets/llms.txt)
1393
+ - **AI Agent Full Manual (`llms-full.txt`)**: [https://react-native-vu.github.io/react-native-live-widgets/llms-full.txt](https://react-native-vu.github.io/react-native-live-widgets/llms-full.txt)
1394
+
1395
+ ---
1396
+
1212
1397
  ## 📄 License
1213
1398
  MIT © vu-tran