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.
- package/CHANGELOG.md +7 -0
- package/README.md +40 -1
- package/android/src/main/java/com/reactnativeliveactivity/renderer/DynamicWidgetCanvasRenderer.kt +443 -46
- package/android/src/main/java/com/reactnativeliveactivity/storage/DynamicWidgetStateStore.kt +86 -28
- package/android/src/main/java/com/reactnativeliveactivity/widgets/DynamicHomeScreenWidgetProvider.kt +126 -56
- package/android/src/main/res/layout/rn_live_widget_hit_zone.xml +16 -0
- package/android/src/main/res/layout/rn_live_widget_host.xml +16 -87
- package/docs/GUIDE-EN.md +241 -0
- package/docs/GUIDE-VI.md +266 -0
- package/docs/index.html +1140 -259
- package/docs/llms-full.txt +26 -0
- package/docs/llms.txt +8 -0
- package/ios/Models/DynamicLayoutModels.swift +6 -1
- package/ios/Renderer/DynamicNodeView.swift +169 -14
- package/ios/Widgets/DynamicHomeScreenWidget.swift +5 -0
- package/lib/builder.d.ts.map +1 -1
- package/lib/builder.js +65 -11
- package/lib/builder.js.map +1 -1
- package/lib/dispatcher.js +16 -10
- package/lib/dispatcher.js.map +1 -1
- package/lib/hooks.js +36 -31
- package/lib/hooks.js.map +1 -1
- package/lib/index.d.ts +17 -2
- package/lib/index.d.ts.map +1 -1
- package/lib/index.js +124 -50
- package/lib/index.js.map +1 -1
- package/lib/ir.d.ts +15 -0
- package/lib/ir.d.ts.map +1 -0
- package/lib/ir.js +379 -0
- package/lib/ir.js.map +1 -0
- package/lib/jsx.d.ts +9 -1
- package/lib/jsx.d.ts.map +1 -1
- package/lib/jsx.js +131 -84
- package/lib/jsx.js.map +1 -1
- package/lib/preview.d.ts +0 -23
- package/lib/preview.d.ts.map +1 -1
- package/lib/preview.js +373 -104
- package/lib/preview.js.map +1 -1
- package/lib/types.d.ts +204 -12
- package/lib/types.d.ts.map +1 -1
- package/lib/types.js +2 -1
- package/lib/types.js.map +1 -1
- package/package.json +2 -1
- package/src/builder.ts +57 -2
- package/src/index.ts +66 -1
- package/src/ir.ts +430 -0
- package/src/jsx.tsx +30 -0
- package/src/preview.tsx +356 -32
- package/src/react-native-env.d.ts +1 -0
- 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
|