react-native-live-widgets 1.1.1 → 1.2.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 (58) hide show
  1. package/CHANGELOG.md +21 -0
  2. package/README.md +113 -10
  3. package/android/src/main/java/com/reactnativeliveactivity/bridge/LiveActivityModule.kt +5 -1
  4. package/android/src/main/java/com/reactnativeliveactivity/renderer/DynamicWidgetCanvasRenderer.kt +443 -46
  5. package/android/src/main/java/com/reactnativeliveactivity/storage/DynamicWidgetStateStore.kt +86 -24
  6. package/android/src/main/java/com/reactnativeliveactivity/widgets/DynamicHomeScreenWidgetProvider.kt +126 -56
  7. package/android/src/main/res/layout/rn_live_widget_hit_zone.xml +16 -0
  8. package/android/src/main/res/layout/rn_live_widget_host.xml +16 -87
  9. package/docs/GUIDE-EN.md +332 -7
  10. package/docs/GUIDE-VI.md +357 -7
  11. package/docs/index.html +1143 -227
  12. package/docs/llms-full.txt +46 -6
  13. package/docs/llms.txt +37 -7
  14. package/ios/Models/DynamicLayoutModels.swift +11 -1
  15. package/ios/Renderer/DynamicNodeView.swift +169 -14
  16. package/ios/Widgets/DynamicHomeScreenWidget.swift +7 -3
  17. package/lib/builder.d.ts.map +1 -1
  18. package/lib/builder.js +92 -28
  19. package/lib/builder.js.map +1 -1
  20. package/lib/dispatcher.d.ts +7 -0
  21. package/lib/dispatcher.d.ts.map +1 -1
  22. package/lib/dispatcher.js +23 -6
  23. package/lib/dispatcher.js.map +1 -1
  24. package/lib/hooks.d.ts +66 -0
  25. package/lib/hooks.d.ts.map +1 -0
  26. package/lib/hooks.js +171 -0
  27. package/lib/hooks.js.map +1 -0
  28. package/lib/index.d.ts +48 -8
  29. package/lib/index.d.ts.map +1 -1
  30. package/lib/index.js +216 -35
  31. package/lib/index.js.map +1 -1
  32. package/lib/ir.d.ts +15 -0
  33. package/lib/ir.d.ts.map +1 -0
  34. package/lib/ir.js +379 -0
  35. package/lib/ir.js.map +1 -0
  36. package/lib/jsx.d.ts +87 -0
  37. package/lib/jsx.d.ts.map +1 -0
  38. package/lib/jsx.js +243 -0
  39. package/lib/jsx.js.map +1 -0
  40. package/lib/preview.d.ts +31 -0
  41. package/lib/preview.d.ts.map +1 -0
  42. package/lib/preview.js +735 -0
  43. package/lib/preview.js.map +1 -0
  44. package/lib/types.d.ts +212 -12
  45. package/lib/types.d.ts.map +1 -1
  46. package/lib/types.js +2 -1
  47. package/lib/types.js.map +1 -1
  48. package/package.json +3 -1
  49. package/src/builder.ts +86 -21
  50. package/src/dispatcher.ts +17 -0
  51. package/src/hooks.ts +223 -0
  52. package/src/index.ts +202 -13
  53. package/src/ir.ts +430 -0
  54. package/src/jsx.tsx +326 -0
  55. package/src/preview.tsx +1043 -0
  56. package/src/react-ambient.d.ts +10 -0
  57. package/src/react-native-env.d.ts +44 -0
  58. package/src/types.ts +261 -13
package/docs/GUIDE-VI.md CHANGED
@@ -68,7 +68,7 @@ git clone https://github.com/React-Native-Vu/LiveWidgetsExampleExpo.git
68
68
  cd LiveWidgetsExampleExpo
69
69
  npm install
70
70
  npx expo prebuild
71
- npm run setup:widgets
71
+ npx react-native-live-widgets init
72
72
  npx expo run:ios # hoặc npx expo run:android
73
73
  ```
74
74
 
@@ -237,7 +237,7 @@ async function ensureAndroidNotificationPermission() {
237
237
  ```
238
238
 
239
239
  #### 5. Bước 4: Cách thêm và kéo giãn Home Screen Widget trên Android (`small` / `medium` / `large`)
240
- 1. Sau khi gọi `Widget.update('main', { small, medium, large })` trong app, ra màn hình chính (Home Screen) của Android.
240
+ 1. Sau khi gọi `Widget.setLayout('main', { small, medium, large })` (hoặc alias `Widget.update(...)`) trong app, ra màn hình chính (Home Screen) của Android.
241
241
  2. **Nhấn giữ vào khoảng trống** trên màn hình chính -> Chọn **Widgets (Tiện ích)** -> Tìm ứng dụng của bạn -> Kéo **Live Widgets** ra màn hình.
242
242
  3. **Thay đổi kích thước tự động (Responsive Sizing):** Nhấn giữ vào Widget trên màn hình chính rồi thả tay ra để xuất hiện khung viền 4 chấm tròn:
243
243
  - Kéo thu nhỏ về **2×2 ô** (`chiều rộng < 210dp`): Tự động hiển thị giao diện **`small`** (tỷ lệ vuông 1:1).
@@ -315,7 +315,84 @@ import { LiveActivity, Widget, SharedStorage, UI } from 'react-native-live-widge
315
315
 
316
316
  ## 4. Xây dựng Giao diện Động (Declarative UI Engine)
317
317
 
318
- ### `UI.StyleSheet` & Tái sử dụng Style (`StyleProp`)
318
+ Thư viện hỗ trợ song song **2 phong cách viết giao diện** tùy theo sở thích và thói quen của bạn:
319
+ 1. **Phong cách 1: Dạng JSX / TSX (`<VStack>`, `<Text>`, `<Button>`)** — Giống hệt như viết Component trong React Native, trực quan và dễ bảo trì khi layout lồng ghép nhiều tầng. Hỗ trợ đầy đủ thuộc tính `style` và mảng style có điều kiện.
320
+ 2. **Phong cách 2: Dạng Hàm lồng nhau (`UI.VStack(...)`)** — Phong cách Functional gọn gàng, không cần import nhiều thẻ JSX.
321
+
322
+ Cả 2 cách đều được biên dịch tự động sang cùng một kiến trúc Native (SwiftUI trên iOS và 2D Canvas trên Android).
323
+
324
+ ---
325
+
326
+ ### Phong cách 1: Xây dựng bằng JSX / TSX Component
327
+
328
+ ```tsx
329
+ import React from 'react';
330
+ import { StyleSheet } from 'react-native';
331
+ import { Widget, VStack, HStack, Text, Badge, Progress, Button } from 'react-native-live-widgets';
332
+
333
+ export const MyWidgetLayout = (
334
+ <VStack style={styles.card}>
335
+ <HStack style={styles.header}>
336
+ <Text style={styles.title}>Vào ca sáng</Text>
337
+ <Badge text="07:54 (Hợp lệ)" backgroundColor="#064E3B" textColor="#6EE7B7" />
338
+ </HStack>
339
+ <Progress value={0.75} style="segmented" segments={4} tintColor="#38BDF8" height={8} />
340
+ <Button title="Làm mới dữ liệu" actionId="refresh" fullWidth />
341
+ </VStack>
342
+ );
343
+
344
+ const styles = StyleSheet.create({
345
+ card: {
346
+ padding: 16,
347
+ backgroundColor: '#0F172A',
348
+ borderRadius: 16,
349
+ },
350
+ header: {
351
+ justifyContent: 'space-between',
352
+ marginBottom: 8,
353
+ },
354
+ title: {
355
+ fontSize: 14,
356
+ fontWeight: 'bold',
357
+ color: '#FFFFFF',
358
+ },
359
+ });
360
+ ```
361
+
362
+ ---
363
+
364
+ ### Xem Trước Widget Trong App (`<WidgetPreview>` / `<VoltraWidgetPreview>`)
365
+
366
+ Bạn có thể nhúng widget vào trực tiếp bất kỳ màn hình nào của ứng dụng để xem trước giao diện và bấm thử các nút tương tác mà không cần phải thoát ra Home Screen:
367
+
368
+ ```tsx
369
+ import { WidgetPreview, VStack, HStack, Text, Button } from 'react-native-live-widgets';
370
+
371
+ export function PreviewScreen() {
372
+ return (
373
+ <WidgetPreview
374
+ size="medium" // 'small' | 'medium' | 'large' | 'lockScreen'
375
+ showBadge={true} // Hiển thị 'Medium • 338×158'
376
+ interactiveSizeSwitch={true} // Bật thanh tab để chuyển nhanh small/medium/large
377
+ onAction={(actionId) => {
378
+ console.log('Action được bấm trên widget:', actionId);
379
+ }}
380
+ >
381
+ <VStack padding={16} backgroundColor="#0F172A" borderRadius={20}>
382
+ <HStack justifyContent="spaceBetween">
383
+ <Text fontSize={14} fontWeight="bold" color="#FFFFFF">Tiến độ công việc</Text>
384
+ <Text fontSize={12} color="#38BDF8">75%</Text>
385
+ </HStack>
386
+ <Button title="Cập nhật" actionId="refresh" fullWidth />
387
+ </VStack>
388
+ </WidgetPreview>
389
+ );
390
+ }
391
+ ```
392
+
393
+ ---
394
+
395
+ ### Phong cách 2: Dạng Hàm (`UI.StyleSheet` & Functional DSL)
319
396
  Tương tự như `StyleSheet.create` trong React Native, bạn có thể gom nhóm các style định dạng lại để tái sử dụng nhiều nơi, giữ code sạch sẽ và hỗ trợ truyền mảng style có điều kiện:
320
397
 
321
398
  ```typescript
@@ -744,17 +821,24 @@ if (isSupported) {
744
821
 
745
822
  ## 7. Đồng bộ API Ngầm cho Widget kể cả khi Kill App (`Widget.setRemoteConfig`)
746
823
 
747
- Khi ứng dụng bị người dùng vuốt tắt hoàn toàn (Kill App), JavaScript thread của React Native sẽ dừng. Để Widget vẫn luôn có dữ liệu mới từ Server:
824
+ Khi ứng dụng bị người dùng vuốt tắt hoàn toàn (Kill App), JavaScript thread của React Native sẽ dừng. Để Widget vẫn luôn tự động gọi API lấy dữ liệu mới từ Server:
748
825
 
749
826
  ```typescript
750
- await Widget.setRemoteConfig({
827
+ // Cú pháp tiêu chuẩn đầy đủ:
828
+ await Widget.setRemoteConfig('main', {
751
829
  url: 'https://api.yourcompany.com/v1/widget-summary',
752
830
  method: 'GET',
753
831
  headers: {
754
832
  Authorization: `Bearer ${accessToken}`,
755
833
  },
756
- intervalMinutes: 15, // Tự động đồng bộ mỗi 15 phút ở tầng OS (WidgetKit Timeline / Android AlarmManager)
757
- });
834
+ refreshIntervalMinutes: 15, // Chu kỳ gọi ngầm ở tầng OS (alias: intervalMinutes)
835
+ }, APP_GROUP);
836
+
837
+ // Hoặc cú pháp ngắn gọn (mặc định widgetKey = 'main'):
838
+ await Widget.setRemoteConfig({
839
+ url: 'https://api.yourcompany.com/v1/widget-summary',
840
+ refreshIntervalMinutes: 15,
841
+ }, APP_GROUP);
758
842
  ```
759
843
 
760
844
  - **Cách hoạt động:**
@@ -859,5 +943,271 @@ phases: [
859
943
 
860
944
  ---
861
945
 
946
+ ---
947
+
948
+ ## 12. Hệ thống Styling Modifiers & Bảng Năng lực Nền tảng (Capability & Fallback Matrix)
949
+
950
+ ### 12.1. Styling Modifiers nâng cao
951
+ 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:
952
+
953
+ 1. **🌈 Gradient (Dải màu chuyển sắc)**:
954
+ ```tsx
955
+ <VStack
956
+ gradient={{
957
+ colors: ['#1E3A8A', '#3B82F6'],
958
+ startPoint: { x: 0, y: 0 },
959
+ endPoint: { x: 1, y: 1 },
960
+ angle: 45
961
+ }}
962
+ padding={16}
963
+ >
964
+ <Text typography="headline" color="#FFFFFF">Thẻ chuyển sắc</Text>
965
+ </VStack>
966
+ ```
967
+ > [!TIP]
968
+ > **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.
969
+
970
+ 2. **🔲 Border & Dashed Lines (Đường viền nét đứt)**:
971
+ ```tsx
972
+ <VStack
973
+ borderWidth={1.5}
974
+ borderColor="#38BDF8"
975
+ borderStyle="dashed"
976
+ borderRadius={12}
977
+ padding={12}
978
+ >
979
+ <Text fontSize={12} color="#94A3B8">Khu vực kéo thả hoặc ghi chú</Text>
980
+ </VStack>
981
+ ```
982
+
983
+ 3. **🌑 Shadow (Đổ bóng có chiều sâu)**:
984
+ ```tsx
985
+ <Button
986
+ title="Xác nhận"
987
+ backgroundColor="#2563EB"
988
+ shadowColor="#2563EB"
989
+ shadowRadius={6}
990
+ shadowOpacity={0.4}
991
+ shadowOffset={{ x: 0, y: 3 }}
992
+ />
993
+ ```
994
+
995
+ 4. **🔤 Typography & Dynamic Type (Cỡ chữ chuẩn & Trợ năng)**:
996
+ - 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).
997
+ - `fontDesign`: `'default' | 'monospaced' | 'rounded' | 'serif'`.
998
+ - `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).
999
+
1000
+ 5. **🌗 Tinted / Dark Mode (Chế độ đổi màu iOS 18 & Material You)**:
1001
+ ```tsx
1002
+ <Text color={{ light: '#0F172A', dark: '#F8FAFC', tinted: '#38BDF8' }}>
1003
+ Nội dung tự thích ứng màu sắc
1004
+ </Text>
1005
+ ```
1006
+
1007
+ 6. **🌍 Hỗ trợ bố cục quốc tế hoá RTL**:
1008
+ ```tsx
1009
+ <HStack direction="rtl" isRTL={true} spacing={8}>
1010
+ <Text>مرحبا بك</Text>
1011
+ </HStack>
1012
+ ```
1013
+
1014
+ ---
1015
+
1016
+ ### 12.2. Bảng Tra cứu Năng lực Nền tảng (Platform Capability & Fallback Matrix)
1017
+
1018
+ 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):
1019
+
1020
+ | 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ợ |
1021
+ | :--- | :---: | :---: | :---: | :---: | :--- |
1022
+ | **Bố cục Khai báo (`VStack`/`HStack`/`Grid`)** | ✅ SwiftUI | ✅ SwiftUI | ✅ Canvas | ✅ 2D Canvas | Tương thích pixel 100% hai hệ máy |
1023
+ | **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 |
1024
+ | **Bóng đổ Thẻ / Chữ (Shadow)** | ✅ SwiftUI | ✅ SwiftUI | ⚠️ Text Shadow | ✅ `setShadowLayer` | Tự động hạ cấp sang viền mỏng hoặc Android Elevation |
1025
+ | **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` |
1026
+ | **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 |
1027
+ | **Đảo chiều RTL (Ả Rập, Hebrew)** | ✅ Native | ✅ Native | ✅ RTL | ✅ RTL | Tự động đảo thứ tự hàng ngang sang `row-reverse` |
1028
+ | **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` |
1029
+ | **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 |
1030
+ | **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 |
1031
+
1032
+ ---
1033
+
1034
+ ### 12.3. ♿ Lớp Trợ năng & Ngữ nghĩa (Accessibility Fallback Layer)
1035
+
1036
+ Để đả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:
1037
+
1038
+ ```tsx
1039
+ <VStack padding={16} backgroundColor="#0F172A">
1040
+ {/* Tiêu đề với vai trò Header */}
1041
+ <Text
1042
+ typography="title2"
1043
+ accessibilityRole="header"
1044
+ accessibilityLabel="Bảng điều khiển chấm công"
1045
+ >
1046
+ BẢNG ĐIỀU KHIỂN CHẤM CÔNG
1047
+ </Text>
1048
+
1049
+ {/* Chỉ số tiến độ với nhãn và giá trị âm thanh */}
1050
+ <Progress
1051
+ value={0.86}
1052
+ accessibilityLabel="Tiến độ hoàn thành ca làm việc"
1053
+ accessibilityValue="86 phần trăm"
1054
+ />
1055
+
1056
+ {/* Nút bấm với nhãn và gợi ý hành động */}
1057
+ <Button
1058
+ title="Check-in vào ca"
1059
+ actionId="CHECK_IN"
1060
+ accessibilityRole="button"
1061
+ accessibilityLabel="Check-in vào ca"
1062
+ accessibilityHint="Chạm hai lần để gửi yêu cầu chấm công"
1063
+ />
1064
+
1065
+ {/* Phần tử trang trí (không đọc lên TalkBack/VoiceOver) */}
1066
+ <Image systemName="sparkles" accessible={false} />
1067
+ </VStack>
1068
+ ```
1069
+
1070
+ #### Cơ chế hoạt động của Accessibility Fallback Layer (Phase 1):
1071
+ 1. **Trên iOS**: Map trực tiếp sang SwiftUI `.accessibilityLabel()`, `.accessibilityHint()`, `.accessibilityValue()`, `.accessibilityAddTraits()`. Nếu `accessible={false}`, áp dụng `.accessibilityHidden(true)`.
1072
+ 2. **Trên Android (Canvas 2D)**:
1073
+ - 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`.
1074
+ - 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.
1075
+ 3. **Trong In-App Preview**: Tự động ánh xạ sang `accessible`, `accessibilityLabel`, `accessibilityHint`, `accessibilityRole` của React Native Web/Mobile.
1076
+
1077
+ ---
1078
+
1079
+ ### 12.4. Kiểm tra năng lực thiết bị qua code (`Widget.getCapabilities`)
1080
+ ```typescript
1081
+ const caps = await Widget.getCapabilities();
1082
+ console.log(`Đang chạy trên: ${caps.platform} (OS: ${caps.osVersion})`);
1083
+
1084
+ if (caps.supportsDynamicIsland) {
1085
+ console.log('Thiết bị có Dynamic Island (iPhone 14 Pro/15/16)!');
1086
+ }
1087
+
1088
+ if (caps.supportsTintedMode) {
1089
+ console.log('Hỗ trợ chế độ Tinted Home Screen của iOS 18!');
1090
+ }
1091
+ ```
1092
+
1093
+ ---
1094
+
1095
+ ### 12.5. 🌲 UI Intermediate Representation (IR) & Semantic Tree (Phase 2)
1096
+
1097
+ 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**:
1098
+
1099
+ ```
1100
+ React Native DSL (JSX / UI.*)
1101
+ ↓
1102
+ UI Intermediate Representation (IR v2.0)
1103
+ ├── UI Tree (gán ID duy nhất cho từng Node)
1104
+ ├── Semantic Tree (độc lập hoàn toàn với Renderer)
1105
+ ├── State Bindings (toggle:<key>, page:<id>)
1106
+ └── Renderer Planner (phân loại Native RemoteViews vs Canvas Bitmap)
1107
+ ↓
1108
+ ├── [NATIVE] RemoteViews (TextView, Button, ProgressBar)
1109
+ └── [CANVAS] Canvas 2D Bitmap (Gauge 240°, Equalizer, Shader)
1110
+ ```
1111
+
1112
+ #### Sử dụng API `Widget.inspectIR` và `Widget.compileIR`:
1113
+ ```typescript
1114
+ import { Widget, UI } from 'react-native-live-widgets';
1115
+
1116
+ const layout = UI.VStack({
1117
+ padding: 16,
1118
+ backgroundColor: '#0F172A',
1119
+ children: [
1120
+ UI.Text('BẢNG ĐIỀU KHIỂN CHẤM CÔNG', { typography: 'title2' }),
1121
+ UI.Progress({ value: 0.86, accessibilityLabel: 'Tiến độ hoàn thành ca' }),
1122
+ UI.Button({ title: 'Check In', actionId: 'toggle:attendance' }),
1123
+ UI.Gauge({ value: 0.92, label: 'Hiệu suất' })
1124
+ ]
1125
+ });
1126
+
1127
+ // 1. Phân tích kiến trúc và kế hoạch kết xuất
1128
+ console.log(Widget.inspectIR(layout));
1129
+ /*
1130
+ Output:
1131
+ 🌲 Widget IR v2.0
1132
+ 📊 Chiến lược kết xuất: NATIVE_FIRST_HYBRID
1133
+ - Native RemoteViews nodes: 4
1134
+ - Canvas Bitmap nodes: 1
1135
+
1136
+ ♿ Tóm tắt âm thanh Trợ năng:
1137
+ "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%"
1138
+
1139
+ 🎯 Kế hoạch phân bổ (Render Plan Tree):
1140
+ [NATIVE] 0.0 <Text> role=header label="BẢNG ĐIỀU KHIỂN CHẤM CÔNG"
1141
+ [NATIVE] 0.1 <Progress> role=progressbar label="Tiến độ hoàn thành ca"
1142
+ [NATIVE] 0.2 <Button> role=button label="Check In" (Action: toggle:attendance)
1143
+ [CANVAS] 0.3 <Gauge> role=progressbar label="Hiệu suất"
1144
+
1145
+ ⚡ Liên kết trạng thái (State Bindings):
1146
+ - [TOGGLE] action=toggle:attendance target=attendance
1147
+ */
1148
+
1149
+ // 2. Biên dịch trực tiếp sang IR Object
1150
+ const ir = Widget.compileIR(layout);
1151
+ console.log(ir.semanticSummary);
1152
+ ```
1153
+
1154
+ ---
1155
+
1156
+ ### 12.6. ⚡ Đồng bộ Trạng thái Native, Tối ưu Sub-renderer & Bộ Kiểm thử Tự động
1157
+
1158
+ #### 1. Đồng bộ Trạng thái Hai chiều Native (Phase 4 State Synchronization):
1159
+ - 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).
1160
+ - 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.
1161
+
1162
+ #### 2. Tối ưu Canvas Sub-renderer (Phase 5 RAM & Binder Protection):
1163
+ - 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).
1164
+ - Triệt tiêu hoàn toàn nguy cơ chạm trần bộ nhớ Binder IPC (`TransactionTooLargeException`) trên Android.
1165
+
1166
+ #### 3. Bộ linh kiện Nâng cao & Kiểm thử Tự động (Phase 6):
1167
+ - 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`.
1168
+ - Bộ kiểm thử tự động 100% assertions:
1169
+ ```bash
1170
+ npm test
1171
+ ```
1172
+ Xác minh tự động:
1173
+ - Cây IR AST và gán ID duy nhất.
1174
+ - Lọc bỏ phần tử trang trí (`accessible: false`).
1175
+ - Phân loại Native-first vs Canvas-when-needed.
1176
+ - Trích xuất Two-Way State Bindings.
1177
+ - Tổng hợp câu âm thanh trợ năng TalkBack.
1178
+
1179
+ ---
1180
+
1181
+ ### 12.7. 🎯 Exact Dynamic Hit Layer, Live Chronometer Countdown & Tương thích Swift 6 (v1.2.1)
1182
+
1183
+ 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:
1184
+
1185
+ #### 1. Vùng Bấm Động Từng Pixel (Exact Dynamic Hit Layer)
1186
+ * **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.
1187
+ * **Giải pháp v1.2.1**:
1188
+ - 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`).
1189
+ - 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.
1190
+ - 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.
1191
+ - 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).
1192
+
1193
+ #### 2. Native Live Countdown Chronometer (`android.widget.Chronometer`)
1194
+ * **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.
1195
+ * **Giải pháp v1.2.1**:
1196
+ - Tích hợp thành phần native `android.widget.Chronometer` trong layout host widget.
1197
+ - Tự động cấu hình `setChronometerCountDown(true)` và tính toán `baseMillis = SystemClock.elapsedRealtime() + remainingMillis`.
1198
+ - 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.
1199
+
1200
+ #### 3. Nội suy biến động (Template Interpolation) & Quản lý Trạng thái Khởi tạo
1201
+ * **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.
1202
+ * **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.
1203
+
1204
+ #### 4. Tương thích Toàn diện Swift 6 Language Mode (iOS Xcode)
1205
+ * **Loại bỏ lỗi `type '()' cannot conform to 'View'`**:
1206
+ - Đó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`.
1207
+ - 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`.
1208
+ - Đóng gói `strokeStyle` và bổ sung nhánh fallback `else { EmptyView() }` cho `backgroundView` và `borderOverlay` trong `ContainerStyleModifier`.
1209
+
1210
+ ---
1211
+
862
1212
  ## 📄 License
863
1213
  MIT © vu-tran