react-native-live-widgets 1.2.0 → 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 (50) hide show
  1. package/CHANGELOG.md +7 -0
  2. package/README.md +40 -1
  3. package/android/src/main/java/com/reactnativeliveactivity/renderer/DynamicWidgetCanvasRenderer.kt +443 -46
  4. package/android/src/main/java/com/reactnativeliveactivity/storage/DynamicWidgetStateStore.kt +86 -28
  5. package/android/src/main/java/com/reactnativeliveactivity/widgets/DynamicHomeScreenWidgetProvider.kt +126 -56
  6. package/android/src/main/res/layout/rn_live_widget_hit_zone.xml +16 -0
  7. package/android/src/main/res/layout/rn_live_widget_host.xml +16 -87
  8. package/docs/GUIDE-EN.md +241 -0
  9. package/docs/GUIDE-VI.md +266 -0
  10. package/docs/index.html +1140 -259
  11. package/docs/llms-full.txt +26 -0
  12. package/docs/llms.txt +8 -0
  13. package/ios/Models/DynamicLayoutModels.swift +6 -1
  14. package/ios/Renderer/DynamicNodeView.swift +169 -14
  15. package/ios/Widgets/DynamicHomeScreenWidget.swift +5 -0
  16. package/lib/builder.d.ts.map +1 -1
  17. package/lib/builder.js +65 -11
  18. package/lib/builder.js.map +1 -1
  19. package/lib/dispatcher.js +16 -10
  20. package/lib/dispatcher.js.map +1 -1
  21. package/lib/hooks.js +36 -31
  22. package/lib/hooks.js.map +1 -1
  23. package/lib/index.d.ts +17 -2
  24. package/lib/index.d.ts.map +1 -1
  25. package/lib/index.js +124 -50
  26. package/lib/index.js.map +1 -1
  27. package/lib/ir.d.ts +15 -0
  28. package/lib/ir.d.ts.map +1 -0
  29. package/lib/ir.js +379 -0
  30. package/lib/ir.js.map +1 -0
  31. package/lib/jsx.d.ts +9 -1
  32. package/lib/jsx.d.ts.map +1 -1
  33. package/lib/jsx.js +131 -84
  34. package/lib/jsx.js.map +1 -1
  35. package/lib/preview.d.ts +0 -23
  36. package/lib/preview.d.ts.map +1 -1
  37. package/lib/preview.js +373 -104
  38. package/lib/preview.js.map +1 -1
  39. package/lib/types.d.ts +204 -12
  40. package/lib/types.d.ts.map +1 -1
  41. package/lib/types.js +2 -1
  42. package/lib/types.js.map +1 -1
  43. package/package.json +2 -1
  44. package/src/builder.ts +57 -2
  45. package/src/index.ts +66 -1
  46. package/src/ir.ts +430 -0
  47. package/src/jsx.tsx +30 -0
  48. package/src/preview.tsx +356 -32
  49. package/src/react-native-env.d.ts +1 -0
  50. package/src/types.ts +253 -13
package/docs/GUIDE-EN.md CHANGED
@@ -944,6 +944,247 @@ phases: [
944
944
 
945
945
  ---
946
946
 
947
+ ---
948
+
949
+ ## 12. Advanced Styling Modifiers & Platform Capability Matrix
950
+
951
+ ### 12.1. Styling Modifiers Reference
952
+
953
+ Elevate your widgets and Live Activities with design system fundamentals:
954
+
955
+ 1. **🌈 Linear & Radial Gradients**:
956
+ ```tsx
957
+ <VStack
958
+ gradient={{
959
+ colors: ['#1E3A8A', '#3B82F6'],
960
+ startPoint: { x: 0, y: 0 },
961
+ endPoint: { x: 1, y: 1 },
962
+ angle: 45,
963
+ }}
964
+ padding={16}
965
+ >
966
+ <Text typography="headline" color="#FFFFFF">Gradient Card</Text>
967
+ </VStack>
968
+ ```
969
+ > [!TIP]
970
+ > **Graceful Fallback**: If an older OS version or platform does not support gradient shaders, the renderer automatically uses the first color in `colors` as the solid fallback `backgroundColor`.
971
+
972
+ 2. **🔲 Borders & Dashed Lines**:
973
+ ```tsx
974
+ <VStack
975
+ borderWidth={1.5}
976
+ borderColor="#38BDF8"
977
+ borderStyle="dashed"
978
+ borderRadius={12}
979
+ padding={12}
980
+ >
981
+ <Text fontSize={12} color="#94A3B8">Dashed card border</Text>
982
+ </VStack>
983
+ ```
984
+
985
+ 3. **🌑 Shadows & Elevation**:
986
+ ```tsx
987
+ <Button
988
+ title="Confirm"
989
+ backgroundColor="#2563EB"
990
+ shadowColor="#2563EB"
991
+ shadowRadius={6}
992
+ shadowOpacity={0.4}
993
+ shadowOffset={{ x: 0, y: 3 }}
994
+ />
995
+ ```
996
+
997
+ 4. **🔤 Typography & Dynamic Type (Accessibility Scaling)**:
998
+ - Scale levels: `largeTitle` (34), `title1` (28), `title2` (22), `title3` (20), `headline` (17 bold), `body` (17 regular), `callout` (16), `subheadline` (15), `footnote` (13), `caption1` (12), `caption2` (11).
999
+ - `fontDesign`: `'default' | 'monospaced' | 'rounded' | 'serif'`.
1000
+ - `dynamicType`: Defaults to `true` — automatically respects the user's OS Accessibility font size setting.
1001
+
1002
+ 5. **🌗 Tinted / Dark Mode (iOS 18 Accentable & Android Dynamic Theming)**:
1003
+ ```tsx
1004
+ <Text color={{ light: '#0F172A', dark: '#F8FAFC', tinted: '#38BDF8' }}>
1005
+ Theme-adaptive text
1006
+ </Text>
1007
+ ```
1008
+
1009
+ 6. **🌍 RTL Internationalization**:
1010
+ ```tsx
1011
+ <HStack direction="rtl" isRTL={true} spacing={8}>
1012
+ <Text>مرحبا بك</Text>
1013
+ </HStack>
1014
+ ```
1015
+
1016
+ ---
1017
+
1018
+ ### 12.2. Platform Capability & Fallback Matrix
1019
+
1020
+ Rather than making unverified claims of "100% parity", the engine provides an explicit, transparent capability matrix paired with automatic **Graceful Fallbacks**:
1021
+
1022
+ | Feature / Modifier | iOS WidgetKit | iOS Live Activity | Android Ongoing Notification | Android Home Widget | Graceful Fallback Strategy |
1023
+ | :--- | :---: | :---: | :---: | :---: | :--- |
1024
+ | **Declarative Layouts (`VStack`/`HStack`/`Grid`)** | ✅ SwiftUI | ✅ SwiftUI | ✅ Canvas | ✅ 2D Canvas | 100% pixel-aligned cross-platform |
1025
+ | **Linear / Radial Gradients** | ✅ SwiftUI | ✅ SwiftUI | ✅ Shader | ✅ Shader | Automatically falls back to dominant solid `backgroundColor` |
1026
+ | **Card & Text Shadows** | ✅ SwiftUI | ✅ SwiftUI | ⚠️ Text Only | ✅ `setShadowLayer` | Falls back to elevation or thin border stroke |
1027
+ | **Dashed / Dotted Borders** | ✅ StrokeStyle | ✅ StrokeStyle | ⚠️ Solid | ✅ `DashPathEffect` | Automatically falls back to solid border |
1028
+ | **Dynamic Type (Accessibility)** | ✅ Native | ✅ Native | ✅ `fontScale` | ✅ `fontScale` | Automatically scales with OS font multiplier |
1029
+ | **RTL Layout Mirroring** | ✅ Native | ✅ Native | ✅ RTL | ✅ RTL | Reverses flex order and flips text alignment |
1030
+ | **Accessibility (TalkBack / VoiceOver)** | ✅ Native VoiceOver | ✅ Native VoiceOver | ✅ Notification Text | ✅ A11y Summary + Hit-Zones | Aggregated semantic `contentDescription` ensures full screen-reader readability |
1031
+ | **iOS 18 Tinted Mode** | ✅ Accentable | N/A | N/A | ✅ Material You | Resolves `tinted` key on iOS 18; falls back to dark/light color |
1032
+ | **Interactive Background Intents** | ✅ iOS 17+ | ✅ iOS 17+ | ✅ PendingIntent | ✅ PendingIntent | Updates local Shared Storage and refreshes timeline |
1033
+
1034
+ ---
1035
+
1036
+ ### 12.3. ♿ Accessibility & Semantics (Phase 1 Fallback Layer)
1037
+
1038
+ To ensure users with visual impairments or screen-reader users (**VoiceOver on iOS**, **TalkBack on Android**) receive full context, the engine provides standard accessibility props:
1039
+
1040
+ ```tsx
1041
+ <VStack padding={16} backgroundColor="#0F172A">
1042
+ {/* Header with semantic role */}
1043
+ <Text
1044
+ typography="title2"
1045
+ accessibilityRole="header"
1046
+ accessibilityLabel="Shift Attendance Dashboard"
1047
+ >
1048
+ ATTENDANCE DASHBOARD
1049
+ </Text>
1050
+
1051
+ {/* Progress gauge with spoken percentage */}
1052
+ <Progress
1053
+ value={0.86}
1054
+ accessibilityLabel="Shift completion progress"
1055
+ accessibilityValue="86 percent"
1056
+ />
1057
+
1058
+ {/* Interactive button with action hint */}
1059
+ <Button
1060
+ title="Clock In"
1061
+ actionId="CLOCK_IN"
1062
+ accessibilityRole="button"
1063
+ accessibilityLabel="Clock in to shift"
1064
+ accessibilityHint="Double tap to confirm attendance"
1065
+ />
1066
+
1067
+ {/* Decorative element hidden from screen readers */}
1068
+ <Image systemName="sparkles" accessible={false} />
1069
+ </VStack>
1070
+ ```
1071
+
1072
+ #### How Phase 1 Accessibility Works:
1073
+ 1. **iOS (SwiftUI)**: Maps directly to native `.accessibilityLabel()`, `.accessibilityHint()`, `.accessibilityValue()`, and `.accessibilityAddTraits()`. Elements with `accessible={false}` receive `.accessibilityHidden(true)`.
1074
+ 2. **Android (Canvas 2D)**:
1075
+ - Recursively extracts an intelligent text summary (`extractAccessibilitySummary`) and binds it to the canvas `ImageView`'s `contentDescription`.
1076
+ - Each interactive hit-zone receives its own `contentDescription` and action hint so TalkBack speaks each button individually when focused.
1077
+ 3. **In-App Preview**: Maps to React Native Web/Mobile accessibility props.
1078
+
1079
+ ---
1080
+
1081
+ ### 12.4. Programmatic Capability Inspection (`Widget.getCapabilities`)
1082
+ ```typescript
1083
+ const caps = await Widget.getCapabilities();
1084
+ console.log(`Running on: ${caps.platform} (OS: ${caps.osVersion})`);
1085
+
1086
+ if (caps.supportsDynamicIsland) {
1087
+ console.log('Device has Dynamic Island hardware!');
1088
+ }
1089
+
1090
+ if (caps.supportsTintedMode) {
1091
+ console.log('Device supports iOS 18 Tinted Home Screen mode!');
1092
+ }
1093
+ ```
1094
+
1095
+ ---
1096
+
1097
+ ### 12.5. 🌲 UI Intermediate Representation (IR) & Semantic Tree (Phase 2)
1098
+
1099
+ Rather than compiling directly from `DSL ➔ Canvas Bitmap`, the engine introduces a decoupled **UI Intermediate Representation (IR v2.0)** and a **Renderer Planner**:
1100
+
1101
+ ```
1102
+ React Native DSL (JSX / UI.*)
1103
+ ↓
1104
+ UI Intermediate Representation (IR v2.0)
1105
+ ├── UI Tree (unique ID for every node)
1106
+ ├── Semantic Tree (independent of visual renderer)
1107
+ ├── State Bindings (toggle:<key>, page:<id>)
1108
+ └── Renderer Planner (classifies Native RemoteViews vs Canvas Bitmap)
1109
+ ↓
1110
+ ├── [NATIVE] RemoteViews (TextView, Button, ProgressBar)
1111
+ └── [CANVAS] Canvas 2D Bitmap (Gauge 240°, Equalizer, Shader)
1112
+ ```
1113
+
1114
+ #### Inspecting and Compiling IR:
1115
+ ```typescript
1116
+ import { Widget, UI } from 'react-native-live-widgets';
1117
+
1118
+ const layout = UI.VStack({
1119
+ padding: 16,
1120
+ backgroundColor: '#0F172A',
1121
+ children: [
1122
+ UI.Text('ATTENDANCE DASHBOARD', { typography: 'title2' }),
1123
+ UI.Progress({ value: 0.86, accessibilityLabel: 'Shift completion' }),
1124
+ UI.Button({ title: 'Clock In', actionId: 'toggle:attendance' }),
1125
+ UI.Gauge({ value: 0.92, label: 'Efficiency' })
1126
+ ]
1127
+ });
1128
+
1129
+ // 1. Inspect architectural plan and accessibility synthesis
1130
+ console.log(Widget.inspectIR(layout));
1131
+
1132
+ // 2. Compile to raw IR object
1133
+ const ir = Widget.compileIR(layout);
1134
+ console.log('Synthesized A11y Summary:', ir.semanticSummary);
1135
+ ```
1136
+
1137
+ ---
1138
+
1139
+ ### 12.6. ⚡ Native State Sync, Sub-renderer Optimization & Automated Test Suite
1140
+
1141
+ #### 1. Native State Synchronization (Phase 4):
1142
+ - Instant action & toggle responses: Native Android (`LiveActivityReceiver.kt` & `DynamicWidgetStateStore`) immediately updates `SharedPreferences` and triggers a widget redraw with zero UI lag even if the app was killed.
1143
+ - React hooks (`useWidgetStorage`, `useWidgetAction`) reconcile the latest state upon app launch.
1144
+
1145
+ #### 2. Canvas Sub-renderer Optimization (Phase 5):
1146
+ - `renderSubNodeBitmap`: Isolates bitmap allocation solely to the sub-component's bounding box (e.g. 64dp Gauge consumes only ~40KB bitmap) instead of allocating a full-screen canvas bitmap.
1147
+ - Completely avoids Android Binder IPC `TransactionTooLargeException`.
1148
+
1149
+ #### 3. Advanced JSX Components & Automated Tests (Phase 6):
1150
+ - New JSX components: `<Toggle>`, `<Switch>`, and `<Checkbox>` with `checked`/`isChecked`, `tintColor`, and `strikethroughOnCheck`.
1151
+ - Automated test suite verifying 100% assertions:
1152
+ ```bash
1153
+ npm test
1154
+ ```
1155
+
1156
+ ---
1157
+
1158
+ ### 12.7. 🎯 Exact Dynamic Hit Layer, Live Chronometer Countdown & Swift 6 Compatibility (v1.2.1)
1159
+
1160
+ Version **v1.2.1** addresses critical real-world interaction challenges on physical devices:
1161
+
1162
+ #### 1. Exact Dynamic Hit Layer
1163
+ * **Previous Issue**: With static coordinate grids, layout reflows or dynamic content caused buttons to trigger adjacent items or blank spaces to activate phantom taps.
1164
+ * **v1.2.1 Solution**:
1165
+ - Replaced the fixed grid with a dynamic `FrameLayout` container (`rn_hit_layer` paired with `rn_live_widget_hit_zone.xml`).
1166
+ - Implemented the **`computeCanvasMapping`** algorithm to calculate aspect ratio letterboxing (`fitCenter`) between the Canvas Bitmap and the Launcher Widget bounds.
1167
+ - Generates independent RemoteViews hit zones that align 100% with the rendered element bounding box. Empty areas receive no touch events.
1168
+
1169
+ #### 2. Native Live Countdown Chronometer (`android.widget.Chronometer`)
1170
+ * **Previous Issue**: Drawing countdown text directly on Canvas required broadcasting and re-rendering the bitmap every second, causing battery drain and rate-limiting from Android system schedulers.
1171
+ * **v1.2.1 Solution**:
1172
+ - Integrated native `android.widget.Chronometer` into the widget host layout.
1173
+ - Automatically configured with `setChronometerCountDown(true)` and `baseMillis = SystemClock.elapsedRealtime() + remainingMillis`.
1174
+ - The renderer suppresses static timer text when an active chronometer is present, allowing continuous 1-second countdown ticks driven natively by Android OS.
1175
+
1176
+ #### 3. Dynamic Template Variable Interpolation & Initial State Store
1177
+ * **Variable Interpolation**: Supports dynamic string templates (`{{id}}`, `{{title}}`, counter values) directly in the layout JSON, automatically resolved against action responses and local state.
1178
+ * **`defaultChecked` Persistence**: Switches and checkboxes with `checked: true` have their initial state committed to `DynamicWidgetStateStore` on initial render, allowing them to be toggled off immediately on the first tap.
1179
+
1180
+ #### 4. Swift 6 Language Mode Compatibility (iOS Xcode)
1181
+ * **Resolved `type '()' cannot conform to 'View'`**:
1182
+ - Encapsulated `Font` resolution in `renderText()` within self-invoking closures `{ ... }()`.
1183
+ - Refactored `DynamicNodeAccessibilityModifier` procedural assignments into a dedicated `buildAccessibilityView(content:) -> AnyView` helper method.
1184
+ - Added fallback `else { EmptyView() }` branches to `backgroundView` and `borderOverlay` in `ContainerStyleModifier`.
1185
+
1186
+ ---
1187
+
947
1188
  ## 📄 License
948
1189
  MIT © vu-tran
949
1190
 
package/docs/GUIDE-VI.md CHANGED
@@ -943,5 +943,271 @@ phases: [
943
943
 
944
944
  ---
945
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
+
946
1212
  ## 📄 License
947
1213
  MIT © vu-tran