react-native-live-widgets 1.2.0 → 1.2.2

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 (87) hide show
  1. package/CHANGELOG.md +34 -0
  2. package/README.md +129 -50
  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 +529 -59
  9. package/android/src/main/java/com/reactnativeliveactivity/storage/DynamicWidgetImageCache.kt +53 -0
  10. package/android/src/main/java/com/reactnativeliveactivity/storage/DynamicWidgetStateStore.kt +684 -83
  11. package/android/src/main/java/com/reactnativeliveactivity/widgets/DynamicHomeScreenWidgetProvider.kt +129 -57
  12. package/android/src/main/java/com/reactnativeliveactivity/widgets/DynamicQuickSettingsTileService.kt +120 -0
  13. package/android/src/main/res/layout/rn_live_widget_hit_zone.xml +16 -0
  14. package/android/src/main/res/layout/rn_live_widget_host.xml +16 -87
  15. package/app.plugin.js +36 -0
  16. package/assets/MaterialIcons.json +2236 -0
  17. package/cli/codegen.js +789 -0
  18. package/cli/setup.js +323 -63
  19. package/docs/EXPO-GUIDE-EN.md +21 -3
  20. package/docs/EXPO-GUIDE-VI.md +21 -3
  21. package/docs/GUIDE-EN.md +444 -21
  22. package/docs/GUIDE-VI.md +473 -22
  23. package/docs/index.html +2263 -265
  24. package/docs/llms-full.txt +41 -0
  25. package/docs/llms.txt +24 -7
  26. package/ios/Bridge/LiveActivityModule.swift +333 -44
  27. package/ios/Intents/DynamicWidgetActionIntent.swift +57 -2
  28. package/ios/Models/DynamicLayoutModels.swift +120 -5
  29. package/ios/Renderer/DynamicNodeView.swift +184 -20
  30. package/ios/Storage/DynamicWidgetStateStore.swift +649 -38
  31. package/ios/Widgets/DynamicControlWidget.swift +63 -0
  32. package/ios/Widgets/DynamicHomeScreenWidget.swift +104 -26
  33. package/ios/Widgets/DynamicLiveActivityWidget.swift +25 -4
  34. package/lib/builder.d.ts +50 -7
  35. package/lib/builder.d.ts.map +1 -1
  36. package/lib/builder.js +391 -29
  37. package/lib/builder.js.map +1 -1
  38. package/lib/dispatcher.js +16 -10
  39. package/lib/dispatcher.js.map +1 -1
  40. package/lib/hooks.d.ts +13 -9
  41. package/lib/hooks.d.ts.map +1 -1
  42. package/lib/hooks.js +105 -42
  43. package/lib/hooks.js.map +1 -1
  44. package/lib/index.d.ts +96 -8
  45. package/lib/index.d.ts.map +1 -1
  46. package/lib/index.js +415 -97
  47. package/lib/index.js.map +1 -1
  48. package/lib/ir.d.ts +15 -0
  49. package/lib/ir.d.ts.map +1 -0
  50. package/lib/ir.js +386 -0
  51. package/lib/ir.js.map +1 -0
  52. package/lib/jsx.d.ts +19 -7
  53. package/lib/jsx.d.ts.map +1 -1
  54. package/lib/jsx.js +179 -95
  55. package/lib/jsx.js.map +1 -1
  56. package/lib/material-icons.generated.d.ts +8 -0
  57. package/lib/material-icons.generated.d.ts.map +1 -0
  58. package/lib/material-icons.generated.js +9 -0
  59. package/lib/material-icons.generated.js.map +1 -0
  60. package/lib/preview.d.ts +11 -27
  61. package/lib/preview.d.ts.map +1 -1
  62. package/lib/preview.js +456 -119
  63. package/lib/preview.js.map +1 -1
  64. package/lib/sf-symbols.generated.d.ts +8 -0
  65. package/lib/sf-symbols.generated.d.ts.map +1 -0
  66. package/lib/sf-symbols.generated.js +9 -0
  67. package/lib/sf-symbols.generated.js.map +1 -0
  68. package/lib/types.d.ts +506 -30
  69. package/lib/types.d.ts.map +1 -1
  70. package/lib/types.js +2 -1
  71. package/lib/types.js.map +1 -1
  72. package/package.json +7 -2
  73. package/scripts/build.js +98 -0
  74. package/scripts/generate-material-icons.js +93 -0
  75. package/scripts/generate-sf-symbols.js +95 -0
  76. package/scripts/release.js +115 -0
  77. package/scripts/test-ir-semantic.js +314 -0
  78. package/src/builder.ts +439 -26
  79. package/src/hooks.ts +88 -12
  80. package/src/index.ts +385 -57
  81. package/src/ir.ts +436 -0
  82. package/src/jsx.tsx +99 -21
  83. package/src/material-icons.generated.ts +3844 -0
  84. package/src/preview.tsx +533 -55
  85. package/src/react-native-env.d.ts +1 -0
  86. package/src/sf-symbols.generated.ts +9533 -0
  87. package/src/types.ts +601 -31
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
@@ -943,5 +983,416 @@ phases: [
943
983
 
944
984
  ---
945
985
 
986
+ ---
987
+
988
+ ## 12. Hệ thống Styling Modifiers & Bảng Năng lực Nền tảng (Capability & Fallback Matrix)
989
+
990
+ ### 12.1. Styling Modifiers nâng cao
991
+ Bộ thuộc tính thiết kế nền tảng giúp Widget và Live Activity đạt chuẩn giao diện iOS & Android chuyên nghiệp:
992
+
993
+ 1. **🌈 Gradient (Dải màu chuyển sắc)**:
994
+ ```tsx
995
+ <VStack
996
+ gradient={{
997
+ colors: ['#1E3A8A', '#3B82F6'],
998
+ startPoint: { x: 0, y: 0 },
999
+ endPoint: { x: 1, y: 1 },
1000
+ angle: 45
1001
+ }}
1002
+ padding={16}
1003
+ >
1004
+ <Text typography="headline" color="#FFFFFF">Thẻ chuyển sắc</Text>
1005
+ </VStack>
1006
+ ```
1007
+ > [!TIP]
1008
+ > **Graceful Fallback**: Nếu hệ điều hành hoặc thiết bị cũ không hỗ trợ vẽ gradient, engine tự động lấy màu đầu tiên trong danh sách `colors` làm màu nền đơn sắc (`backgroundColor`) thay thế, hoàn toàn không gây lỗi giao diện.
1009
+
1010
+ 2. **🔲 Border & Dashed Lines (Đường viền nét đứt)**:
1011
+ ```tsx
1012
+ <VStack
1013
+ borderWidth={1.5}
1014
+ borderColor="#38BDF8"
1015
+ borderStyle="dashed"
1016
+ borderRadius={12}
1017
+ padding={12}
1018
+ >
1019
+ <Text fontSize={12} color="#94A3B8">Khu vực kéo thả hoặc ghi chú</Text>
1020
+ </VStack>
1021
+ ```
1022
+
1023
+ 3. **🌑 Shadow (Đổ bóng có chiều sâu)**:
1024
+ ```tsx
1025
+ <Button
1026
+ title="Xác nhận"
1027
+ backgroundColor="#2563EB"
1028
+ shadowColor="#2563EB"
1029
+ shadowRadius={6}
1030
+ shadowOpacity={0.4}
1031
+ shadowOffset={{ x: 0, y: 3 }}
1032
+ />
1033
+ ```
1034
+
1035
+ 4. **🔤 Typography & Dynamic Type (Cỡ chữ chuẩn & Trợ năng)**:
1036
+ - Các bậc cỡ chữ chuẩn: `largeTitle` (34), `title1` (28), `title2` (22), `title3` (20), `headline` (17 bold), `body` (17 regular), `callout` (16), `subheadline` (15), `footnote` (13), `caption1` (12), `caption2` (11).
1037
+ - `fontDesign`: `'default' | 'monospaced' | 'rounded' | 'serif'`.
1038
+ - `dynamicType`: Mặc định `true` — tự động co giãn theo cỡ chữ Trợ năng mà người dùng cài đặt trong Cài đặt hệ thống (Accessibility Font Size).
1039
+
1040
+ 5. **🌗 Tinted / Dark Mode (Chế độ đổi màu iOS 18 & Material You)**:
1041
+ ```tsx
1042
+ <Text color={{ light: '#0F172A', dark: '#F8FAFC', tinted: '#38BDF8' }}>
1043
+ Nội dung tự thích ứng màu sắc
1044
+ </Text>
1045
+ ```
1046
+
1047
+ 6. **🌍 Hỗ trợ bố cục quốc tế hoá RTL**:
1048
+ ```tsx
1049
+ <HStack direction="rtl" isRTL={true} spacing={8}>
1050
+ <Text>مرحبا بك</Text>
1051
+ </HStack>
1052
+ ```
1053
+
1054
+ ---
1055
+
1056
+ ### 12.2. Bảng Tra cứu Năng lực Nền tảng (Platform Capability & Fallback Matrix)
1057
+
1058
+ Thay vì tuyên bố chung chung "100% parity", engine phân định rõ ràng các tính năng thực tế được hỗ trợ trên từng hệ điều hành và cơ chế tự động chuyển đổi an toàn (Graceful Fallback):
1059
+
1060
+ | Tính năng / Thuộc tính | iOS WidgetKit | iOS Live Activity | Android Ongoing Notification | Android Home Widget | Cơ chế Graceful Fallback khi không hỗ trợ |
1061
+ | :--- | :---: | :---: | :---: | :---: | :--- |
1062
+ | **Bố cục Khai báo (`VStack`/`HStack`/`Grid`)** | ✅ SwiftUI | ✅ SwiftUI | ✅ Canvas | ✅ 2D Canvas | Tương thích pixel 100% hai hệ máy |
1063
+ | **Linear / Radial Gradient** | ✅ SwiftUI | ✅ SwiftUI | ✅ Shader | ✅ Shader | Tự động lấy màu đầu tiên trong `colors` làm màu nền đơn sắc |
1064
+ | **Bóng đổ Thẻ / Chữ (Shadow)** | ✅ SwiftUI | ✅ SwiftUI | ⚠️ Text Shadow | ✅ `setShadowLayer` | Tự động hạ cấp sang viền mỏng hoặc Android Elevation |
1065
+ | **Viền nét đứt (Dashed / Dotted)** | ✅ StrokeStyle | ✅ StrokeStyle | ⚠️ Nét liền | ✅ `DashPathEffect` | Tự động hiển thị viền nét liền `solid` |
1066
+ | **Dynamic Type (Cỡ chữ Trợ năng)** | ✅ Native | ✅ Native | ✅ `fontScale` | ✅ `fontScale` | Tự động nhân tỉ lệ fontScale của hệ điều hành |
1067
+ | **Đảo chiều RTL (Ả Rập, Hebrew)** | ✅ Native | ✅ Native | ✅ RTL | ✅ RTL | Tự động đảo thứ tự hàng ngang sang `row-reverse` |
1068
+ | **Accessibility (TalkBack / VoiceOver)** | ✅ Native VoiceOver | ✅ Native VoiceOver | ✅ Notification Text | ✅ A11y Summary + Hit-Zones | Tổng hợp ngữ nghĩa toàn cây gán vào `contentDescription` |
1069
+ | **Chế độ Tinted (iOS 18+)** | ✅ Accentable | Không áp dụng | Không áp dụng | ✅ Material You | Tự động dùng màu `dark`/`light` trên iOS 17 trở xuống |
1070
+ | **Nút bấm tương tác chạy ngầm** | ✅ iOS 17+ AppIntent | ✅ iOS 17+ | ✅ PendingIntent | ✅ PendingIntent | Lưu trạng thái SharedStorage và kích hoạt làm mới giao diện |
1071
+
1072
+ ---
1073
+
1074
+ ### 12.3. ♿ Lớp Trợ năng & Ngữ nghĩa (Accessibility Fallback Layer)
1075
+
1076
+ Để đảm bảo người khiếm thị hoặc người sử dụng công cụ đọc màn hình (**VoiceOver trên iOS**, **TalkBack trên Android**) tiếp cận được đầy đủ thông tin trên Widget, engine cung cấp các thuộc tính Trợ năng chuẩn:
1077
+
1078
+ ```tsx
1079
+ <VStack padding={16} backgroundColor="#0F172A">
1080
+ {/* Tiêu đề với vai trò Header */}
1081
+ <Text
1082
+ typography="title2"
1083
+ accessibilityRole="header"
1084
+ accessibilityLabel="Bảng điều khiển chấm công"
1085
+ >
1086
+ BẢNG ĐIỀU KHIỂN CHẤM CÔNG
1087
+ </Text>
1088
+
1089
+ {/* Chỉ số tiến độ với nhãn và giá trị âm thanh */}
1090
+ <Progress
1091
+ value={0.86}
1092
+ accessibilityLabel="Tiến độ hoàn thành ca làm việc"
1093
+ accessibilityValue="86 phần trăm"
1094
+ />
1095
+
1096
+ {/* Nút bấm với nhãn và gợi ý hành động */}
1097
+ <Button
1098
+ title="Check-in vào ca"
1099
+ actionId="CHECK_IN"
1100
+ accessibilityRole="button"
1101
+ accessibilityLabel="Check-in vào ca"
1102
+ accessibilityHint="Chạm hai lần để gửi yêu cầu chấm công"
1103
+ />
1104
+
1105
+ {/* Phần tử trang trí (không đọc lên TalkBack/VoiceOver) */}
1106
+ <Image systemName="sparkles" accessible={false} />
1107
+ </VStack>
1108
+ ```
1109
+
1110
+ #### Cơ chế hoạt động của Accessibility Fallback Layer (Phase 1):
1111
+ 1. **Trên iOS**: Map trực tiếp sang SwiftUI `.accessibilityLabel()`, `.accessibilityHint()`, `.accessibilityValue()`, `.accessibilityAddTraits()`. Nếu `accessible={false}`, áp dụng `.accessibilityHidden(true)`.
1112
+ 2. **Trên Android (Canvas 2D)**:
1113
+ - Toàn bộ cây DSL được duyệt đệ quy để trích xuất một bản tóm tắt âm thanh thông minh (`extractAccessibilitySummary`) và gán vào `contentDescription` của Canvas `ImageView`.
1114
+ - Các nút bấm tương tác (Hit-Zones) được gán `contentDescription` riêng rẽ kèm `accessibilityHint`, giúp TalkBack phát âm chuẩn xác khi người dùng chạm vào từng nút.
1115
+ 3. **Trong In-App Preview**: Tự động ánh xạ sang `accessible`, `accessibilityLabel`, `accessibilityHint`, `accessibilityRole` của React Native Web/Mobile.
1116
+
1117
+ ---
1118
+
1119
+ ### 12.4. Kiểm tra năng lực thiết bị qua code (`Widget.getCapabilities`)
1120
+ ```typescript
1121
+ const caps = await Widget.getCapabilities();
1122
+ console.log(`Đang chạy trên: ${caps.platform} (OS: ${caps.osVersion})`);
1123
+
1124
+ if (caps.supportsDynamicIsland) {
1125
+ console.log('Thiết bị có Dynamic Island (iPhone 14 Pro/15/16)!');
1126
+ }
1127
+
1128
+ if (caps.supportsTintedMode) {
1129
+ console.log('Hỗ trợ chế độ Tinted Home Screen của iOS 18!');
1130
+ }
1131
+ ```
1132
+
1133
+ ---
1134
+
1135
+ ### 12.5. 🌲 UI Intermediate Representation (IR) & Semantic Tree (Phase 2)
1136
+
1137
+ Thay vì đi thẳng từ `DSL ➔ Canvas Bitmap`, kiến trúc v1.2 giới thiệu tầng **UI Intermediate Representation (IR)** và bộ điều phối **Renderer Planner**:
1138
+
1139
+ ```
1140
+ React Native DSL (JSX / UI.*)
1141
+ ↓
1142
+ UI Intermediate Representation (IR v2.0)
1143
+ ├── UI Tree (gán ID duy nhất cho từng Node)
1144
+ ├── Semantic Tree (độc lập hoàn toàn với Renderer)
1145
+ ├── State Bindings (toggle:<key>, page:<id>)
1146
+ └── Renderer Planner (phân loại Native RemoteViews vs Canvas Bitmap)
1147
+ ↓
1148
+ ├── [NATIVE] RemoteViews (TextView, Button, ProgressBar)
1149
+ └── [CANVAS] Canvas 2D Bitmap (Gauge 240°, Equalizer, Shader)
1150
+ ```
1151
+
1152
+ #### Sử dụng API `Widget.inspectIR` và `Widget.compileIR`:
1153
+ ```typescript
1154
+ import { Widget, UI } from 'react-native-live-widgets';
1155
+
1156
+ const layout = UI.VStack({
1157
+ padding: 16,
1158
+ backgroundColor: '#0F172A',
1159
+ children: [
1160
+ UI.Text('BẢNG ĐIỀU KHIỂN CHẤM CÔNG', { typography: 'title2' }),
1161
+ UI.Progress({ value: 0.86, accessibilityLabel: 'Tiến độ hoàn thành ca' }),
1162
+ UI.Button({ title: 'Check In', actionId: 'toggle:attendance' }),
1163
+ UI.Gauge({ value: 0.92, label: 'Hiệu suất' })
1164
+ ]
1165
+ });
1166
+
1167
+ // 1. Phân tích kiến trúc và kế hoạch kết xuất
1168
+ console.log(Widget.inspectIR(layout));
1169
+ /*
1170
+ Output:
1171
+ 🌲 Widget IR v2.0
1172
+ 📊 Chiến lược kết xuất: NATIVE_FIRST_HYBRID
1173
+ - Native RemoteViews nodes: 4
1174
+ - Canvas Bitmap nodes: 1
1175
+
1176
+ ♿ Tóm tắt âm thanh Trợ năng:
1177
+ "BẢNG ĐIỀU KHIỂN CHẤM CÔNG. Tiến độ hoàn thành ca 86%. Nút Check In (Kích hoạt hành động toggle:attendance). Hiệu suất: 92%"
1178
+
1179
+ 🎯 Kế hoạch phân bổ (Render Plan Tree):
1180
+ [NATIVE] 0.0 <Text> role=header label="BẢNG ĐIỀU KHIỂN CHẤM CÔNG"
1181
+ [NATIVE] 0.1 <Progress> role=progressbar label="Tiến độ hoàn thành ca"
1182
+ [NATIVE] 0.2 <Button> role=button label="Check In" (Action: toggle:attendance)
1183
+ [CANVAS] 0.3 <Gauge> role=progressbar label="Hiệu suất"
1184
+
1185
+ ⚡ Liên kết trạng thái (State Bindings):
1186
+ - [TOGGLE] action=toggle:attendance target=attendance
1187
+ */
1188
+
1189
+ // 2. Biên dịch trực tiếp sang IR Object
1190
+ const ir = Widget.compileIR(layout);
1191
+ console.log(ir.semanticSummary);
1192
+ ```
1193
+
1194
+ ---
1195
+
1196
+ ### 12.6. ⚡ Đồng bộ Trạng thái Native, Tối ưu Sub-renderer & Bộ Kiểm thử Tự động
1197
+
1198
+ #### 1. Đồng bộ Trạng thái Hai chiều Native (Phase 4 State Synchronization):
1199
+ - Khi người dùng chạm nút hoặc đổi toggle trên Widget, Android Native (`LiveActivityReceiver.kt` & `DynamicWidgetStateStore`) **ngay lập tức lưu trạng thái mới vào SharedPreferences** và kích hoạt re-render widget ngay tức khắc, không có độ trễ và không bị lệch trạng thái kể cả khi App đã bị tắt (Force-Killed).
1200
+ - Khi App React Native mở lên, hook `useWidgetStorage` và `useWidgetAction` tự động đồng bộ lại state mới nhất từ Native Store.
1201
+
1202
+ #### 2. Tối ưu Canvas Sub-renderer (Phase 5 RAM & Binder Protection):
1203
+ - Thay vì vẽ một tấm Bitmap khổng lồ chiếm hàng Megabyte cho toàn bộ màn hình, phương thức `renderSubNodeBitmap` chỉ vẽ đúng kích thước khung hình hộp bao của thành phần đồ họa (ví dụ Gauge 64dp chỉ tốn ~40KB bitmap).
1204
+ - Triệt tiêu hoàn toàn nguy cơ chạm trần bộ nhớ Binder IPC (`TransactionTooLargeException`) trên Android.
1205
+
1206
+ #### 3. Bộ linh kiện Nâng cao & Kiểm thử Tự động (Phase 6):
1207
+ - Bổ sung các thẻ JSX: `<Toggle>`, `<Switch>`, `<Checkbox>` với trạng thái `checked`/`isChecked`, tự động đổi màu `tintColor` và gạch ngang chữ `strikethroughOnCheck`.
1208
+ - Bộ kiểm thử tự động 100% assertions:
1209
+ ```bash
1210
+ npm test
1211
+ ```
1212
+ Xác minh tự động:
1213
+ - Cây IR AST và gán ID duy nhất.
1214
+ - Lọc bỏ phần tử trang trí (`accessible: false`).
1215
+ - Phân loại Native-first vs Canvas-when-needed.
1216
+ - Trích xuất Two-Way State Bindings.
1217
+ - Tổng hợp câu âm thanh trợ năng TalkBack.
1218
+
1219
+ ---
1220
+
1221
+ ### 12.7. 🎯 Exact Dynamic Hit Layer, Live Chronometer Countdown & Tương thích Swift 6 (v1.2.1)
1222
+
1223
+ Phiên bản **v1.2.1** giải quyết dứt điểm các bài toán thực tế khi triển khai Widget tương tác phức tạp trên thiết bị người dùng thật:
1224
+
1225
+ #### 1. Vùng Bấm Động Từng Pixel (Exact Dynamic Hit Layer)
1226
+ * **Vấn đề trước đây**: Khi dùng lưới tọa độ cố định, nếu các thành phần trong layout co giãn hoặc nằm lệch dòng, người dùng bấm vào một nút có thể bị ăn sang nút khác, hoặc bấm vào vùng trống lại kích hoạt nhầm sự kiện.
1227
+ * **Giải pháp v1.2.1**:
1228
+ - Toàn bộ lưới cố định được thay bằng container `FrameLayout` động (`rn_hit_layer` kết hợp `rn_live_widget_hit_zone.xml`).
1229
+ - Giải thuật **`computeCanvasMapping`** tự động tính toán bù trừ tỷ lệ co giãn (`fitCenter` letterboxing) giữa kích thước Canvas Bitmap thật và màn hình widget Launcher.
1230
+ - Mỗi phần tử tương tác (Button, Checkbox, Switch, Link) được sinh một vùng RemoteViews độc lập khớp chính xác 100% với bounding box được vẽ trên Bitmap.
1231
+ - Vùng trống hoàn toàn không nhận sự kiện, triệt tiêu mọi cú chạm ảo (ghost clicks / phantom taps).
1232
+
1233
+ #### 2. Native Live Countdown Chronometer (`android.widget.Chronometer`)
1234
+ * **Vấn đề trước đây**: Vẽ chữ đếm ngược tĩnh trên Canvas đòi hỏi phải gửi broadcast và render lại bitmap mỗi giây. Điều này gây hao pin, chậm phản hồi và hệ điều hành Android có thể chặn vì spam update quá tần suất.
1235
+ * **Giải pháp v1.2.1**:
1236
+ - Tích hợp thành phần native `android.widget.Chronometer` trong layout host widget.
1237
+ - Tự động cấu hình `setChronometerCountDown(true)` và tính toán `baseMillis = SystemClock.elapsedRealtime() + remainingMillis`.
1238
+ - Renderer tự động ẩn dòng chữ đếm ngược tĩnh trên Bitmap khi có Chronometer hoạt động. Widget đếm ngược mượt mà từng giây trực tiếp từ hệ thống Android mà không cần vẽ lại Bitmap.
1239
+
1240
+ #### 3. Nội suy biến động (Template Interpolation) & Quản lý Trạng thái Khởi tạo
1241
+ * **Nội suy chuỗi biến số**: Hỗ trợ cú pháp template `{{id}}`, `{{title}}`, và giá trị bộ đếm phẳng `counterVal`. Bạn có thể truyền động mã phiếu, tiêu đề công việc hoặc số lượt đếm từ API vào layout JSON.
1242
+ * **Xử lý `defaultChecked`**: Trong `DynamicWidgetStateStore`, trạng thái ban đầu của switch (`checked: true`) được tự động lưu vào store ngay lần kết xuất đầu tiên. Người dùng có thể tắt switch ngay từ lần chạm đầu tiên mà không bị reset về trạng thái mặc định.
1243
+
1244
+ #### 4. Tương thích Toàn diện Swift 6 Language Mode (iOS Xcode)
1245
+ * **Loại bỏ lỗi `type '()' cannot conform to 'View'`**:
1246
+ - Đóng gói toàn bộ logic tính `Font` trong `renderText()` vào closure độc lập `{ ... }()`, ngăn compiler Swift 6 hiểu nhầm các câu lệnh điều kiện `if/switch` là View `Void`.
1247
+ - Tách logic phân giải `DynamicNodeAccessibilityModifier` sang hàm helper thuần `buildAccessibilityView(content:) -> AnyView`, tránh xung đột với `@ViewBuilder` ngầm định của protocol `ViewModifier`.
1248
+ - Đóng gói `strokeStyle` và bổ sung nhánh fallback `else { EmptyView() }` cho `backgroundView` và `borderOverlay` trong `ContainerStyleModifier`.
1249
+
1250
+ ---
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
+
946
1397
  ## 📄 License
947
1398
  MIT © vu-tran