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.
- package/CHANGELOG.md +34 -0
- package/README.md +129 -50
- package/android/src/main/AndroidManifest.xml +12 -0
- package/android/src/main/assets/fonts/MaterialIcons-Regular.ttf +0 -0
- package/android/src/main/java/com/reactnativeliveactivity/bridge/LiveActivityModule.kt +61 -1
- package/android/src/main/java/com/reactnativeliveactivity/liveactivity/LiveActivityNotifier.kt +153 -17
- package/android/src/main/java/com/reactnativeliveactivity/liveactivity/LiveActivityReceiver.kt +1 -1
- package/android/src/main/java/com/reactnativeliveactivity/renderer/DynamicWidgetCanvasRenderer.kt +529 -59
- package/android/src/main/java/com/reactnativeliveactivity/storage/DynamicWidgetImageCache.kt +53 -0
- package/android/src/main/java/com/reactnativeliveactivity/storage/DynamicWidgetStateStore.kt +684 -83
- package/android/src/main/java/com/reactnativeliveactivity/widgets/DynamicHomeScreenWidgetProvider.kt +129 -57
- package/android/src/main/java/com/reactnativeliveactivity/widgets/DynamicQuickSettingsTileService.kt +120 -0
- 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/app.plugin.js +36 -0
- package/assets/MaterialIcons.json +2236 -0
- package/cli/codegen.js +789 -0
- package/cli/setup.js +323 -63
- package/docs/EXPO-GUIDE-EN.md +21 -3
- package/docs/EXPO-GUIDE-VI.md +21 -3
- package/docs/GUIDE-EN.md +444 -21
- package/docs/GUIDE-VI.md +473 -22
- package/docs/index.html +2263 -265
- package/docs/llms-full.txt +41 -0
- package/docs/llms.txt +24 -7
- package/ios/Bridge/LiveActivityModule.swift +333 -44
- package/ios/Intents/DynamicWidgetActionIntent.swift +57 -2
- package/ios/Models/DynamicLayoutModels.swift +120 -5
- package/ios/Renderer/DynamicNodeView.swift +184 -20
- package/ios/Storage/DynamicWidgetStateStore.swift +649 -38
- package/ios/Widgets/DynamicControlWidget.swift +63 -0
- package/ios/Widgets/DynamicHomeScreenWidget.swift +104 -26
- package/ios/Widgets/DynamicLiveActivityWidget.swift +25 -4
- package/lib/builder.d.ts +50 -7
- package/lib/builder.d.ts.map +1 -1
- package/lib/builder.js +391 -29
- package/lib/builder.js.map +1 -1
- package/lib/dispatcher.js +16 -10
- package/lib/dispatcher.js.map +1 -1
- package/lib/hooks.d.ts +13 -9
- package/lib/hooks.d.ts.map +1 -1
- package/lib/hooks.js +105 -42
- package/lib/hooks.js.map +1 -1
- package/lib/index.d.ts +96 -8
- package/lib/index.d.ts.map +1 -1
- package/lib/index.js +415 -97
- 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 +386 -0
- package/lib/ir.js.map +1 -0
- package/lib/jsx.d.ts +19 -7
- package/lib/jsx.d.ts.map +1 -1
- package/lib/jsx.js +179 -95
- package/lib/jsx.js.map +1 -1
- package/lib/material-icons.generated.d.ts +8 -0
- package/lib/material-icons.generated.d.ts.map +1 -0
- package/lib/material-icons.generated.js +9 -0
- package/lib/material-icons.generated.js.map +1 -0
- package/lib/preview.d.ts +11 -27
- package/lib/preview.d.ts.map +1 -1
- package/lib/preview.js +456 -119
- package/lib/preview.js.map +1 -1
- package/lib/sf-symbols.generated.d.ts +8 -0
- package/lib/sf-symbols.generated.d.ts.map +1 -0
- package/lib/sf-symbols.generated.js +9 -0
- package/lib/sf-symbols.generated.js.map +1 -0
- package/lib/types.d.ts +506 -30
- package/lib/types.d.ts.map +1 -1
- package/lib/types.js +2 -1
- package/lib/types.js.map +1 -1
- package/package.json +7 -2
- package/scripts/build.js +98 -0
- package/scripts/generate-material-icons.js +93 -0
- package/scripts/generate-sf-symbols.js +95 -0
- package/scripts/release.js +115 -0
- package/scripts/test-ir-semantic.js +314 -0
- package/src/builder.ts +439 -26
- package/src/hooks.ts +88 -12
- package/src/index.ts +385 -57
- package/src/ir.ts +436 -0
- package/src/jsx.tsx +99 -21
- package/src/material-icons.generated.ts +3844 -0
- package/src/preview.tsx +533 -55
- package/src/react-native-env.d.ts +1 -0
- package/src/sf-symbols.generated.ts +9533 -0
- package/src/types.ts +601 -31
package/src/types.ts
CHANGED
|
@@ -27,28 +27,142 @@ export type LayoutNodeType =
|
|
|
27
27
|
| 'Custom';
|
|
28
28
|
|
|
29
29
|
/**
|
|
30
|
-
* Định dạng màu hỗ
|
|
31
|
-
*
|
|
30
|
+
* Định dạng màu hỗ trợ:
|
|
31
|
+
* - Chuỗi Hex đơn (ví dụ '#0F172A', '#38BDF8AA')
|
|
32
|
+
* - Object Dynamic Color tự đổi theo chế độ Sáng / Tối (Light / Dark Mode)
|
|
33
|
+
* - Chế độ Tinted / Accented trên iOS 18+ và Material You Android.
|
|
32
34
|
*/
|
|
33
|
-
export type DynamicColor =
|
|
35
|
+
export type DynamicColor =
|
|
36
|
+
| string
|
|
37
|
+
| {
|
|
38
|
+
light: string;
|
|
39
|
+
dark: string;
|
|
40
|
+
/** Màu hiển thị ở chế độ Tinted Home Screen trên iOS 18+ hoặc Material You Dynamic Theming Android */
|
|
41
|
+
tinted?: string;
|
|
42
|
+
};
|
|
43
|
+
|
|
44
|
+
export type BorderStyle = 'solid' | 'dashed' | 'dotted';
|
|
45
|
+
|
|
46
|
+
/** Cấu hình đổ bóng (Shadow Modifier) cho Card, Button và Container */
|
|
47
|
+
export interface ShadowProps {
|
|
48
|
+
/** Màu bóng đổ (hỗ trợ DynamicColor) */
|
|
49
|
+
shadowColor?: DynamicColor;
|
|
50
|
+
/** Bán kính mờ của bóng đổ (dp/pt) */
|
|
51
|
+
shadowRadius?: number;
|
|
52
|
+
/** Độ mờ đục từ 0.0 (trong suốt) đến 1.0 (đậm đặc) */
|
|
53
|
+
shadowOpacity?: number;
|
|
54
|
+
/** Độ dời vị trí bóng đổ theo trục X và Y */
|
|
55
|
+
shadowOffset?: { x: number; y: number };
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
/** Cấu hình dải màu chuyển sắc (Gradient Modifier) */
|
|
59
|
+
export interface GradientProps {
|
|
60
|
+
/** Kiểu chuyển sắc: 'linear' (đường thẳng - mặc định) hoặc 'radial' (tâm tròn) */
|
|
61
|
+
type?: 'linear' | 'radial';
|
|
62
|
+
/** Danh sách các màu chuyển tiếp (hỗ trợ DynamicColor cho từng chặng) */
|
|
63
|
+
colors: DynamicColor[];
|
|
64
|
+
/** Điểm bắt đầu theo toạ độ tỉ lệ từ 0.0 đến 1.0 (mặc định { x: 0, y: 0 } top-left) */
|
|
65
|
+
startPoint?: { x: number; y: number };
|
|
66
|
+
/** Điểm kết thúc theo toạ độ tỉ lệ từ 0.0 đến 1.0 (mặc định { x: 1, y: 1 } bottom-right) */
|
|
67
|
+
endPoint?: { x: number; y: number };
|
|
68
|
+
/** Góc gradient theo độ (ví dụ 45, 90, 180) */
|
|
69
|
+
angle?: number;
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
export type TypographyStyle =
|
|
73
|
+
| 'largeTitle'
|
|
74
|
+
| 'title1'
|
|
75
|
+
| 'title2'
|
|
76
|
+
| 'title3'
|
|
77
|
+
| 'headline'
|
|
78
|
+
| 'subheadline'
|
|
79
|
+
| 'body'
|
|
80
|
+
| 'callout'
|
|
81
|
+
| 'footnote'
|
|
82
|
+
| 'caption1'
|
|
83
|
+
| 'caption2';
|
|
84
|
+
|
|
85
|
+
export type FontDesign = 'default' | 'monospaced' | 'rounded' | 'serif';
|
|
86
|
+
|
|
87
|
+
/**
|
|
88
|
+
* ♿ Vai trò ngữ nghĩa cho Trợ năng (Accessibility Semantic Role).
|
|
89
|
+
* Giúp các công cụ đọc màn hình (TalkBack trên Android, VoiceOver trên iOS, Screen Readers)
|
|
90
|
+
* phát âm chính xác bản chất của phần tử thay vì coi tất cả là hình ảnh raster.
|
|
91
|
+
*/
|
|
92
|
+
export type AccessibilityRole =
|
|
93
|
+
| 'none'
|
|
94
|
+
| 'button'
|
|
95
|
+
| 'header'
|
|
96
|
+
| 'text'
|
|
97
|
+
| 'image'
|
|
98
|
+
| 'progressbar'
|
|
99
|
+
| 'timer'
|
|
100
|
+
| 'switch'
|
|
101
|
+
| 'checkbox'
|
|
102
|
+
| 'summary'
|
|
103
|
+
| 'alert';
|
|
104
|
+
|
|
105
|
+
/**
|
|
106
|
+
* ♿ Thuộc tính Trợ năng (Accessibility & Semantics Layer).
|
|
107
|
+
* Tách biệt hoàn toàn tầng ngữ nghĩa khỏi tầng vẽ đồ họa (Canvas/SwiftUI),
|
|
108
|
+
* cho phép TalkBack và VoiceOver tiếp cận dữ liệu chính xác ngay cả khi render bằng Canvas.
|
|
109
|
+
*/
|
|
110
|
+
export interface AccessibilityProps {
|
|
111
|
+
/** Cho phép công cụ trợ năng (TalkBack/VoiceOver) tiếp cận thành phần này (mặc định true; đặt false cho các icon/hình trang trí decorative) */
|
|
112
|
+
accessible?: boolean;
|
|
113
|
+
/** Mô tả âm thanh phát âm cho người dùng khi TalkBack/VoiceOver lướt tới phần tử */
|
|
114
|
+
accessibilityLabel?: string;
|
|
115
|
+
/** Hướng dẫn hành động bổ sung (ví dụ: "Chạm hai lần để xác nhận chấm công") */
|
|
116
|
+
accessibilityHint?: string;
|
|
117
|
+
/** Vai trò ngữ nghĩa của phần tử (header, button, progressbar, ...) */
|
|
118
|
+
accessibilityRole?: AccessibilityRole;
|
|
119
|
+
/** Giá trị trạng thái đọc lên (ví dụ: "86%", "Đang vận chuyển", "Đã bật") */
|
|
120
|
+
accessibilityValue?: string | number;
|
|
121
|
+
}
|
|
34
122
|
|
|
35
123
|
export interface BaseNode {
|
|
36
124
|
type: LayoutNodeType;
|
|
37
125
|
}
|
|
38
126
|
|
|
39
|
-
export interface ContainerProps {
|
|
127
|
+
export interface ContainerProps extends ShadowProps, AccessibilityProps {
|
|
40
128
|
padding?: number;
|
|
41
129
|
paddingHorizontal?: number;
|
|
42
130
|
paddingVertical?: number;
|
|
43
131
|
spacing?: number;
|
|
132
|
+
/** Khoảng cách giữa các phần tử con (Alias chuẩn React Native Style cho spacing) */
|
|
133
|
+
gap?: number;
|
|
134
|
+
rowGap?: number;
|
|
135
|
+
columnGap?: number;
|
|
44
136
|
backgroundColor?: DynamicColor;
|
|
137
|
+
/** Gradient màu nền (tự động graceful fallback sang backgroundColor nếu platform không hỗ trợ) */
|
|
138
|
+
gradient?: GradientProps;
|
|
45
139
|
borderRadius?: number;
|
|
46
140
|
/** Alias bo góc theo cú pháp SwiftUI (tự động ánh xạ sang borderRadius) */
|
|
47
141
|
cornerRadius?: number;
|
|
48
142
|
borderColor?: DynamicColor;
|
|
49
143
|
borderWidth?: number;
|
|
50
|
-
|
|
51
|
-
|
|
144
|
+
borderStyle?: BorderStyle;
|
|
145
|
+
alignment?:
|
|
146
|
+
| 'leading'
|
|
147
|
+
| 'center'
|
|
148
|
+
| 'trailing'
|
|
149
|
+
| 'top'
|
|
150
|
+
| 'bottom'
|
|
151
|
+
| 'firstTextBaseline'
|
|
152
|
+
| 'lastTextBaseline'
|
|
153
|
+
| string;
|
|
154
|
+
justifyContent?:
|
|
155
|
+
| 'flexStart'
|
|
156
|
+
| 'center'
|
|
157
|
+
| 'flexEnd'
|
|
158
|
+
| 'spaceBetween'
|
|
159
|
+
| 'spaceAround'
|
|
160
|
+
| 'spaceEvenly'
|
|
161
|
+
| string;
|
|
162
|
+
/** Chiều viết văn bản (Hỗ trợ quốc tế hoá RTL cho tiếng Ả Rập, Do Thái) */
|
|
163
|
+
direction?: 'ltr' | 'rtl' | 'auto';
|
|
164
|
+
/** Cờ bật RTL chủ động cho khối container này */
|
|
165
|
+
isRTL?: boolean;
|
|
52
166
|
/** Tự động ẩn hoặc làm mờ nội dung khi thiết bị đang khóa màn hình (Bảo mật chuẩn Apple) */
|
|
53
167
|
privacySensitive?: boolean;
|
|
54
168
|
/** Chủ động che nội dung thành vệt khối mờ Placeholder (Skeleton Redaction) */
|
|
@@ -65,10 +179,19 @@ export type FontWeight =
|
|
|
65
179
|
| (string & {})
|
|
66
180
|
| string;
|
|
67
181
|
|
|
68
|
-
export interface TextStyle {
|
|
182
|
+
export interface TextStyle extends ShadowProps, AccessibilityProps {
|
|
69
183
|
color?: DynamicColor;
|
|
70
184
|
fontSize?: number;
|
|
71
185
|
fontWeight?: FontWeight;
|
|
186
|
+
/** Hệ thống phân cấp cỡ chữ chuẩn Apple Human Interface Guidelines / Material Design */
|
|
187
|
+
typography?: TypographyStyle;
|
|
188
|
+
/** Kiểu dáng họ font chữ hệ thống */
|
|
189
|
+
fontDesign?: FontDesign;
|
|
190
|
+
/** Tự động co giãn cỡ chữ theo cài đặt Trợ năng (Accessibility Dynamic Type) của hệ điều hành (mặc định true) */
|
|
191
|
+
dynamicType?: boolean;
|
|
192
|
+
textAlign?: 'left' | 'center' | 'right' | 'leading' | 'trailing' | 'auto';
|
|
193
|
+
lineHeight?: number;
|
|
194
|
+
letterSpacing?: number;
|
|
72
195
|
numberOfLines?: number;
|
|
73
196
|
strikethroughWhenToggled?: string;
|
|
74
197
|
/** Tự động làm mờ hoặc ẩn chữ khi màn hình khóa (iOS Privacy Redacted) */
|
|
@@ -77,6 +200,8 @@ export interface TextStyle {
|
|
|
77
200
|
redacted?: boolean;
|
|
78
201
|
/** Hiệu ứng cuộn lật số mượt mà kiểu Odometer (iOS 16+ numericText animation) khi số liệu thay đổi */
|
|
79
202
|
numericAnimation?: boolean;
|
|
203
|
+
/** Cho phép text tự đổi màu theo chế độ StandBy / Tinted iOS 17+ / iOS 18 */
|
|
204
|
+
widgetAccentable?: boolean;
|
|
80
205
|
}
|
|
81
206
|
|
|
82
207
|
export type StyleProp<T> = T | null | undefined | false | StyleProp<T>[];
|
|
@@ -104,7 +229,7 @@ export interface TextNode extends BaseNode {
|
|
|
104
229
|
|
|
105
230
|
export interface TimerNode extends BaseNode {
|
|
106
231
|
type: 'Timer';
|
|
107
|
-
props: {
|
|
232
|
+
props: AccessibilityProps & {
|
|
108
233
|
/** Epoch timestamp tính bằng giây để đếm tới (hoặc đếm từ) */
|
|
109
234
|
targetTimestamp: number;
|
|
110
235
|
/** 'countdown': đếm ngược tới mốc; 'countup': đếm tiến từ mốc */
|
|
@@ -119,14 +244,14 @@ export interface TimerNode extends BaseNode {
|
|
|
119
244
|
|
|
120
245
|
export interface ProgressNode extends BaseNode {
|
|
121
246
|
type: 'Progress';
|
|
122
|
-
props: {
|
|
247
|
+
props: AccessibilityProps & {
|
|
123
248
|
// ── 1. Nguồn dữ liệu tiến trình ─────────────────────────────
|
|
124
249
|
/** Mốc bắt đầu (epoch giây) nếu dùng timer interval tự chạy */
|
|
125
250
|
startTimestamp?: number;
|
|
126
251
|
/** Mốc kết thúc (epoch giây) */
|
|
127
252
|
targetTimestamp?: number;
|
|
128
|
-
/** Giá trị cố định từ 0.0 đến 1.0
|
|
129
|
-
value?: number
|
|
253
|
+
/** Giá trị cố định từ 0.0 đến 1.0 hoặc biểu thức binding (vd '{{attendance.progress|divide:100}}') */
|
|
254
|
+
value?: number | string | DataBindingField<any>;
|
|
130
255
|
|
|
131
256
|
// ── 2. Kiểu dáng hiển thị (Style & Shape) ───────────────────
|
|
132
257
|
/** 'bar': thanh liền mạch | 'segmented': thanh nhiều chặng | 'circular': vòng tròn % */
|
|
@@ -173,24 +298,56 @@ export interface ProgressNode extends BaseNode {
|
|
|
173
298
|
/** Có hiển thị chữ phần trăm ở góc không (ví dụ "75%") */
|
|
174
299
|
showPercentage?: boolean;
|
|
175
300
|
percentageColor?: DynamicColor;
|
|
301
|
+
/** Cho phép thanh tiến trình đổi màu theo StandBy / Tinted iOS 17+ / iOS 18 */
|
|
302
|
+
widgetAccentable?: boolean;
|
|
176
303
|
};
|
|
177
304
|
}
|
|
178
305
|
|
|
306
|
+
import type { KnownSFSymbol } from './sf-symbols.generated';
|
|
307
|
+
import type { KnownMaterialIcon } from './material-icons.generated';
|
|
308
|
+
|
|
309
|
+
/**
|
|
310
|
+
* Biểu tượng hệ thống SF Symbols trên iOS (tự động đồng bộ từ Apple Xcode/SF Symbols).
|
|
311
|
+
* Hỗ trợ Auto-Complete hơn 9,500+ biểu tượng chuẩn và cho phép nhập chuỗi tùy ý nhờ `(string & {})`.
|
|
312
|
+
*/
|
|
313
|
+
export type SFSymbolName = KnownSFSymbol | (string & {});
|
|
314
|
+
|
|
315
|
+
/**
|
|
316
|
+
* Danh sách gợi ý toàn bộ hơn 3,800+ biểu tượng Google Material Symbols & Icons chính thức trên Android.
|
|
317
|
+
* Tự động kích hoạt gợi ý Auto-Complete / IntelliSense trong IDE (VS Code, Cursor, WebStorm)
|
|
318
|
+
* và vẫn cho phép nhập bất kỳ tên Material Symbol nào khác nhờ `(string & {})`.
|
|
319
|
+
*/
|
|
320
|
+
export type MaterialIconName = KnownMaterialIcon | (string & {});
|
|
321
|
+
|
|
179
322
|
export interface ImageNode extends BaseNode {
|
|
180
323
|
type: 'Image';
|
|
181
|
-
props: {
|
|
324
|
+
props: AccessibilityProps & {
|
|
182
325
|
/** URL ảnh từ mạng (https://...) - Tự động tải, nén tối ưu RAM và cache vào App Group cho Widget & Live Activity */
|
|
183
326
|
url?: string;
|
|
184
327
|
/** Chuỗi ảnh Base64 (có thể kèm tiền tố data:image/png;base64,... hoặc chuỗi raw base64) */
|
|
185
328
|
base64?: string;
|
|
186
329
|
/** Tên ảnh trong Xcode Assets.xcassets hoặc Android drawable */
|
|
187
330
|
assetName?: string;
|
|
331
|
+
/** Tên ảnh riêng cho iOS trong Assets.xcassets */
|
|
332
|
+
iosAssetName?: string;
|
|
333
|
+
/** Tên ảnh riêng cho Android trong res/drawable */
|
|
334
|
+
androidAssetName?: string;
|
|
188
335
|
/** Tên icon hệ thống SF Symbols trên iOS (ví dụ 'person.crop.circle.fill', 'flame.fill', 'cart.fill') */
|
|
189
|
-
systemName?:
|
|
336
|
+
systemName?: SFSymbolName;
|
|
337
|
+
/** Tên icon SF Symbol riêng biệt cho iOS (ưu tiên cao hơn systemName trên iOS) */
|
|
338
|
+
iosSystemName?: SFSymbolName;
|
|
339
|
+
/** Alias cho iosSystemName */
|
|
340
|
+
systemNameIos?: SFSymbolName;
|
|
341
|
+
/** Tên icon Google Material Symbols riêng biệt cho Android (ưu tiên cao hơn systemName trên Android) */
|
|
342
|
+
androidSystemName?: MaterialIconName;
|
|
343
|
+
/** Alias cho androidSystemName */
|
|
344
|
+
systemNameAndroid?: MaterialIconName;
|
|
345
|
+
/** Tên icon Google Material Symbols (tương đương androidSystemName) */
|
|
346
|
+
materialName?: MaterialIconName;
|
|
190
347
|
/** Đường dẫn file cục bộ trong máy */
|
|
191
348
|
filePath?: string;
|
|
192
349
|
/** Icon SF Symbol dự phòng khi ảnh mạng chưa tải xong hoặc lỗi */
|
|
193
|
-
fallbackSystemName?:
|
|
350
|
+
fallbackSystemName?: SFSymbolName;
|
|
194
351
|
width?: number;
|
|
195
352
|
height?: number;
|
|
196
353
|
/** 'fill': phủ kín khung ảnh (crop) | 'fit': vừa khung ảnh */
|
|
@@ -223,7 +380,7 @@ export interface SpacerNode extends BaseNode {
|
|
|
223
380
|
|
|
224
381
|
export interface ButtonNode extends BaseNode {
|
|
225
382
|
type: 'Button';
|
|
226
|
-
props: {
|
|
383
|
+
props: ShadowProps & AccessibilityProps & {
|
|
227
384
|
title: string;
|
|
228
385
|
/**
|
|
229
386
|
* Mã hành động chạy ngầm ngay trên Widget (iOS 17+ AppIntent, không mở App):
|
|
@@ -237,14 +394,21 @@ export interface ButtonNode extends BaseNode {
|
|
|
237
394
|
/** Mở App và điều hướng tới URL Deep Link cụ thể */
|
|
238
395
|
deepLink?: string;
|
|
239
396
|
backgroundColor?: DynamicColor;
|
|
397
|
+
/** Gradient màu nền nút bấm */
|
|
398
|
+
gradient?: GradientProps;
|
|
240
399
|
textColor?: DynamicColor;
|
|
241
400
|
fontSize?: number;
|
|
242
401
|
fontWeight?: 'regular' | 'medium' | 'semibold' | 'bold';
|
|
402
|
+
typography?: TypographyStyle;
|
|
403
|
+
fontDesign?: FontDesign;
|
|
243
404
|
padding?: number;
|
|
244
405
|
paddingHorizontal?: number;
|
|
245
406
|
paddingVertical?: number;
|
|
246
407
|
borderRadius?: number;
|
|
247
408
|
cornerRadius?: number;
|
|
409
|
+
borderColor?: DynamicColor;
|
|
410
|
+
borderWidth?: number;
|
|
411
|
+
borderStyle?: BorderStyle;
|
|
248
412
|
fullWidth?: boolean;
|
|
249
413
|
/** Tiêu đề hiển thị khi nút ở trạng thái đã tick (dùng với actionId 'toggle:<key>') */
|
|
250
414
|
checkedTitle?: string;
|
|
@@ -303,9 +467,9 @@ export interface DividerNode extends BaseNode {
|
|
|
303
467
|
|
|
304
468
|
export interface GaugeNode extends BaseNode {
|
|
305
469
|
type: 'Gauge';
|
|
306
|
-
props: {
|
|
307
|
-
/** Giá trị tiến độ từ 0.0 đến 1.0 */
|
|
308
|
-
value: number
|
|
470
|
+
props: AccessibilityProps & {
|
|
471
|
+
/** Giá trị tiến độ từ 0.0 đến 1.0 hoặc biểu thức binding */
|
|
472
|
+
value: number | string | DataBindingField<any>;
|
|
309
473
|
/** Chuỗi hiển thị chính giữa đồng hồ (vd "85%", "120 km/h", "420") */
|
|
310
474
|
valueText?: string;
|
|
311
475
|
/** Nhãn phụ bên dưới đồng hồ (vd "KPI", "Kcal", "AQI") */
|
|
@@ -324,6 +488,8 @@ export interface GaugeNode extends BaseNode {
|
|
|
324
488
|
strokeWidth?: number;
|
|
325
489
|
/** Tự động ẩn hoặc làm mờ đồng hồ khi màn hình khóa */
|
|
326
490
|
privacySensitive?: boolean;
|
|
491
|
+
/** Cho phép đồng hồ đổi màu theo StandBy / Tinted iOS 17+ / iOS 18 */
|
|
492
|
+
widgetAccentable?: boolean;
|
|
327
493
|
};
|
|
328
494
|
}
|
|
329
495
|
|
|
@@ -350,7 +516,7 @@ export interface ChartNode extends BaseNode {
|
|
|
350
516
|
|
|
351
517
|
export interface ToggleNode extends BaseNode {
|
|
352
518
|
type: 'Toggle';
|
|
353
|
-
props: {
|
|
519
|
+
props: AccessibilityProps & {
|
|
354
520
|
/** Mã định danh toggle (tự động gắn tiền tố 'toggle:' nếu chưa có) */
|
|
355
521
|
actionId: string;
|
|
356
522
|
label: string;
|
|
@@ -358,6 +524,7 @@ export interface ToggleNode extends BaseNode {
|
|
|
358
524
|
/** 'checkbox' (ô tích) | 'switch' (công tắc gạt) */
|
|
359
525
|
style?: 'checkbox' | 'switch';
|
|
360
526
|
checked?: boolean;
|
|
527
|
+
isChecked?: boolean;
|
|
361
528
|
tintColor?: string;
|
|
362
529
|
textColor?: string;
|
|
363
530
|
checkedTextColor?: string;
|
|
@@ -370,7 +537,12 @@ export interface BadgeNode extends BaseNode {
|
|
|
370
537
|
type: 'Badge';
|
|
371
538
|
props: {
|
|
372
539
|
text: string;
|
|
373
|
-
systemName?:
|
|
540
|
+
systemName?: SFSymbolName;
|
|
541
|
+
iosSystemName?: SFSymbolName;
|
|
542
|
+
androidSystemName?: MaterialIconName;
|
|
543
|
+
systemNameIos?: SFSymbolName;
|
|
544
|
+
systemNameAndroid?: MaterialIconName;
|
|
545
|
+
materialName?: MaterialIconName;
|
|
374
546
|
backgroundColor?: string;
|
|
375
547
|
textColor?: string;
|
|
376
548
|
borderColor?: string;
|
|
@@ -455,14 +627,14 @@ export type LayoutNode =
|
|
|
455
627
|
| CustomNode;
|
|
456
628
|
|
|
457
629
|
export interface DynamicIslandConfig {
|
|
458
|
-
compactLeading: LayoutNode;
|
|
459
|
-
compactTrailing: LayoutNode;
|
|
460
|
-
minimal?: LayoutNode;
|
|
630
|
+
compactLeading: LayoutNode | React.ReactNode;
|
|
631
|
+
compactTrailing: LayoutNode | React.ReactNode;
|
|
632
|
+
minimal?: LayoutNode | React.ReactNode;
|
|
461
633
|
expanded?: {
|
|
462
|
-
leading?: LayoutNode;
|
|
463
|
-
trailing?: LayoutNode;
|
|
464
|
-
bottom?: LayoutNode;
|
|
465
|
-
center?: LayoutNode;
|
|
634
|
+
leading?: LayoutNode | React.ReactNode;
|
|
635
|
+
trailing?: LayoutNode | React.ReactNode;
|
|
636
|
+
bottom?: LayoutNode | React.ReactNode;
|
|
637
|
+
center?: LayoutNode | React.ReactNode;
|
|
466
638
|
};
|
|
467
639
|
}
|
|
468
640
|
|
|
@@ -474,14 +646,53 @@ export interface PhaseConfig {
|
|
|
474
646
|
alertBody?: string;
|
|
475
647
|
}
|
|
476
648
|
|
|
649
|
+
export interface AlertConfig {
|
|
650
|
+
title: string;
|
|
651
|
+
body: string;
|
|
652
|
+
sound?: 'default' | string;
|
|
653
|
+
}
|
|
654
|
+
|
|
655
|
+
export type LiveActivityLifecycleState =
|
|
656
|
+
| 'active'
|
|
657
|
+
| 'started_by_push'
|
|
658
|
+
| 'stale'
|
|
659
|
+
| 'expired'
|
|
660
|
+
| 'ended'
|
|
661
|
+
| 'dismissed';
|
|
662
|
+
|
|
663
|
+
export interface LiveActivityStateEvent {
|
|
664
|
+
activityId: string;
|
|
665
|
+
systemActivityId?: string;
|
|
666
|
+
state: LiveActivityLifecycleState;
|
|
667
|
+
timestamp: number;
|
|
668
|
+
pushToken?: string;
|
|
669
|
+
}
|
|
670
|
+
|
|
477
671
|
export interface StartActivityOptions {
|
|
478
672
|
activityId: string;
|
|
479
673
|
lockScreen: LayoutNode;
|
|
480
674
|
dynamicIsland?: DynamicIslandConfig;
|
|
481
675
|
phases?: PhaseConfig[];
|
|
676
|
+
/** Epoch timestamp (giây hoặc ms) mà từ thời điểm đó Activity bị coi là cũ (Stale) */
|
|
482
677
|
staleTimestamp?: number;
|
|
678
|
+
/** Giao diện Lock Screen dự phòng hiển thị khi Activity chuyển sang trạng thái Stale */
|
|
679
|
+
staleLockScreen?: LayoutNode;
|
|
680
|
+
/** Giao diện Dynamic Island dự phòng hiển thị khi Activity chuyển sang trạng thái Stale */
|
|
681
|
+
staleDynamicIsland?: DynamicIslandConfig;
|
|
682
|
+
/** Điểm ưu tiên hiển thị trên Lock Screen & Dynamic Island khi có nhiều Live Activity (0.0 -> 100.0) */
|
|
683
|
+
relevanceScore?: number;
|
|
684
|
+
/** Cấu hình cảnh báo chuông / banner khi khởi chạy hoặc cập nhật */
|
|
685
|
+
alertConfig?: AlertConfig;
|
|
483
686
|
alertTitle?: string;
|
|
484
687
|
alertBody?: string;
|
|
688
|
+
/** Epoch timestamp (giây hoặc ms) tự động kết thúc Activity khi đến hạn */
|
|
689
|
+
scheduledEndTimestamp?: number;
|
|
690
|
+
/** Hoặc số giây tự động kết thúc tính từ lúc gọi start() */
|
|
691
|
+
autoEndAfterSeconds?: number;
|
|
692
|
+
/** Giao diện Lock Screen tổng kết tự động hiển thị khi Activity hết hạn (Scheduled End) */
|
|
693
|
+
expiredLockScreen?: LayoutNode;
|
|
694
|
+
/** Chính sách dọn dẹp sau khi hết hạn tự động */
|
|
695
|
+
expiredDismissalPolicy?: 'immediate' | 'default' | 'afterDate';
|
|
485
696
|
}
|
|
486
697
|
|
|
487
698
|
export interface UpdateActivityOptions {
|
|
@@ -489,8 +700,16 @@ export interface UpdateActivityOptions {
|
|
|
489
700
|
lockScreen?: LayoutNode;
|
|
490
701
|
dynamicIsland?: DynamicIslandConfig;
|
|
491
702
|
staleTimestamp?: number;
|
|
703
|
+
staleLockScreen?: LayoutNode;
|
|
704
|
+
staleDynamicIsland?: DynamicIslandConfig;
|
|
705
|
+
relevanceScore?: number;
|
|
706
|
+
alertConfig?: AlertConfig;
|
|
492
707
|
alertTitle?: string;
|
|
493
708
|
alertBody?: string;
|
|
709
|
+
scheduledEndTimestamp?: number;
|
|
710
|
+
autoEndAfterSeconds?: number;
|
|
711
|
+
expiredLockScreen?: LayoutNode;
|
|
712
|
+
expiredDismissalPolicy?: 'immediate' | 'default' | 'afterDate';
|
|
494
713
|
}
|
|
495
714
|
|
|
496
715
|
export interface EndActivityOptions {
|
|
@@ -513,6 +732,10 @@ export interface WidgetSinglePageConfig {
|
|
|
513
732
|
small?: LayoutNode;
|
|
514
733
|
medium?: LayoutNode;
|
|
515
734
|
large?: LayoutNode;
|
|
735
|
+
/** Tiện ích cỡ cực đại cho iPadOS / Tablet (systemExtraLarge) & Android 4x4+ */
|
|
736
|
+
extraLarge?: LayoutNode;
|
|
737
|
+
/** Chế độ iOS 17+ StandBy Mode (hiển thị chữ/số lớn khi đặt ngang sạc pin đầu giường) */
|
|
738
|
+
standBy?: LayoutNode;
|
|
516
739
|
/** Màn hình khóa iOS 16+: Tiện ích hình chữ nhật bo góc dưới đồng hồ */
|
|
517
740
|
accessoryRectangular?: LayoutNode;
|
|
518
741
|
/** Màn hình khóa iOS 16+: Tiện ích ô tròn nhỏ dưới đồng hồ (Gauge / Circular Progress / Icon) */
|
|
@@ -521,6 +744,20 @@ export interface WidgetSinglePageConfig {
|
|
|
521
744
|
accessoryInline?: LayoutNode;
|
|
522
745
|
}
|
|
523
746
|
|
|
747
|
+
/** Cấu hình Control Widget (iOS 18+ Control Center / Action Button & Android Quick Settings Tile) */
|
|
748
|
+
export interface ControlWidgetConfig {
|
|
749
|
+
type?: 'button' | 'toggle';
|
|
750
|
+
title: string;
|
|
751
|
+
subtitle?: string;
|
|
752
|
+
checkedTitle?: string;
|
|
753
|
+
checkedSubtitle?: string;
|
|
754
|
+
systemName?: SFSymbolName;
|
|
755
|
+
tintColor?: string;
|
|
756
|
+
checked?: boolean;
|
|
757
|
+
actionId: string;
|
|
758
|
+
deepLink?: string;
|
|
759
|
+
}
|
|
760
|
+
|
|
524
761
|
export interface WidgetLayoutConfig extends WidgetSinglePageConfig {
|
|
525
762
|
/**
|
|
526
763
|
* Danh sách các trang/tab của Widget để chuyển qua lại ngay trên mặt Widget (không mở App).
|
|
@@ -550,6 +787,8 @@ export interface WidgetTimelineEntry {
|
|
|
550
787
|
date: number | string;
|
|
551
788
|
/** Cấu hình layout tại mốc thời gian tương ứng */
|
|
552
789
|
layout: WidgetLayoutConfig;
|
|
790
|
+
/** Dữ liệu Data Binding (tùy chọn) để nội suy sẵn vào layout tại mốc thời gian này */
|
|
791
|
+
data?: Record<string, any>;
|
|
553
792
|
}
|
|
554
793
|
|
|
555
794
|
export interface WidgetTimelineConfig {
|
|
@@ -573,19 +812,121 @@ export interface WidgetConfigOption {
|
|
|
573
812
|
icon?: string;
|
|
574
813
|
}
|
|
575
814
|
|
|
576
|
-
export interface
|
|
577
|
-
/**
|
|
815
|
+
export interface WidgetDataSchema {
|
|
816
|
+
/** Danh sách các key bắt buộc phải có trong dữ liệu sau khi flatten (vd ['user.name', 'attendance.progress']) */
|
|
817
|
+
requiredKeys?: string[];
|
|
818
|
+
/** Kiểm tra kiểu giá trị cơ bản của các key */
|
|
819
|
+
types?: Record<string, 'string' | 'number' | 'boolean'>;
|
|
820
|
+
/** Giá trị mặc định bù vào nếu key bị thiếu hoặc null */
|
|
821
|
+
defaults?: Record<string, string | number | boolean>;
|
|
822
|
+
}
|
|
823
|
+
|
|
824
|
+
export interface WidgetAuthRefreshConfig {
|
|
825
|
+
/** Endpoint cấp lại Access Token khi request chính gặp HTTP 401 */
|
|
826
|
+
url: string;
|
|
827
|
+
method?: 'POST' | 'GET';
|
|
828
|
+
headers?: Record<string, string>;
|
|
829
|
+
body?: string | Record<string, any>;
|
|
830
|
+
/** Đường dẫn JSON lấy token mới từ phản hồi (mặc định 'accessToken' hoặc 'token') */
|
|
831
|
+
tokenPath?: string;
|
|
832
|
+
/** Tên header gắn token mới (mặc định 'Authorization') */
|
|
833
|
+
headerName?: string;
|
|
834
|
+
/** Tiền tố giá trị header (mặc định 'Bearer ') */
|
|
835
|
+
headerPrefix?: string;
|
|
836
|
+
}
|
|
837
|
+
|
|
838
|
+
export interface WidgetRemoteSourceConfig {
|
|
578
839
|
url: string;
|
|
840
|
+
method?: 'GET' | 'POST' | 'PUT';
|
|
841
|
+
headers?: Record<string, string>;
|
|
842
|
+
body?: string | Record<string, any>;
|
|
843
|
+
timeoutMs?: number;
|
|
844
|
+
enableETag?: boolean;
|
|
845
|
+
}
|
|
846
|
+
|
|
847
|
+
export interface WidgetRemoteConfig {
|
|
848
|
+
/** URL API chính mà Widget Extension sẽ tự gọi ngầm (kể cả khi App chính đã bị kill) */
|
|
849
|
+
url?: string;
|
|
579
850
|
/** HTTP Method (mặc định 'GET') */
|
|
580
|
-
method?: 'GET' | 'POST';
|
|
851
|
+
method?: 'GET' | 'POST' | 'PUT';
|
|
852
|
+
/** Payload gửi kèm cho POST / PUT */
|
|
853
|
+
body?: string | Record<string, any>;
|
|
581
854
|
/** Headers xác thực (ví dụ { Authorization: 'Bearer ...' }) */
|
|
582
855
|
headers?: Record<string, string>;
|
|
583
|
-
/**
|
|
856
|
+
/** Thời gian chờ phản hồi mạng tính bằng mili-giây (mặc định 8000ms) */
|
|
857
|
+
timeoutMs?: number;
|
|
858
|
+
/** Thời gian sống của cache (giây) để tránh gọi API liên tục khi OS reload timeline */
|
|
859
|
+
cacheTtlSeconds?: number;
|
|
860
|
+
/** Bật Conditional Request qua header If-None-Match / If-Modified-Since & HTTP 304 */
|
|
861
|
+
enableETag?: boolean;
|
|
862
|
+
/** Số lần thử lại tối đa khi lỗi mạng hoặc HTTP 5xx (mặc định 0, exponential backoff) */
|
|
863
|
+
maxRetries?: number;
|
|
864
|
+
/** Độ trễ gốc (ms) cho lần retry đầu tiên (mặc định 500ms) */
|
|
865
|
+
retryDelayMs?: number;
|
|
866
|
+
/** Gọi đồng thời nhiều nguồn API, biến được gộp theo tiền tố `<sourceKey>.<path>` */
|
|
867
|
+
sources?: Record<string, WidgetRemoteSourceConfig>;
|
|
868
|
+
/** Ánh xạ tên biến đích: { targetKey: 'source.path|pipe' } */
|
|
869
|
+
mapping?: Record<string, string>;
|
|
870
|
+
/** Kiểm định dữ liệu trước khi cập nhật biến hiển thị trên Widget */
|
|
871
|
+
schema?: WidgetDataSchema;
|
|
872
|
+
/** Cấu hình tự động làm mới token nếu API trả HTTP 401 */
|
|
873
|
+
authRefresh?: WidgetAuthRefreshConfig;
|
|
874
|
+
/** Layout hiển thị dự phòng khi đồng bộ lỗi (hoặc dùng biến `{{_syncStatus}}`, `{{_syncError}}`, `{{_httpStatus}}`) */
|
|
875
|
+
errorFallback?: LayoutNode;
|
|
876
|
+
/**
|
|
877
|
+
* Mốc thời gian đề xuất sớm nhất (phút) cho OS tải lại timeline.
|
|
878
|
+
* Lưu ý: iOS WidgetKit dùng ngân sách động (~40–70 lần/ngày) và Android có Doze Mode,
|
|
879
|
+
* nên đây không phải cam kết đồng bộ chính xác từng phút khi app đóng.
|
|
880
|
+
*/
|
|
584
881
|
refreshIntervalMinutes?: number;
|
|
585
882
|
/** Alias ngắn gọn cho refreshIntervalMinutes */
|
|
586
883
|
intervalMinutes?: number;
|
|
587
884
|
}
|
|
588
885
|
|
|
886
|
+
// ─── 13B. STRUCTURED DATA BINDING ────────────────────────────────────────────
|
|
887
|
+
|
|
888
|
+
export interface WidgetDataPipeOptions {
|
|
889
|
+
default?: string | number | boolean;
|
|
890
|
+
divide?: number;
|
|
891
|
+
multiply?: number;
|
|
892
|
+
add?: number;
|
|
893
|
+
round?: number;
|
|
894
|
+
upper?: boolean;
|
|
895
|
+
lower?: boolean;
|
|
896
|
+
currency?: string;
|
|
897
|
+
percent?: number;
|
|
898
|
+
ifTruthy?: [string | number, (string | number)?];
|
|
899
|
+
}
|
|
900
|
+
|
|
901
|
+
export interface DataBindingMethods<V = any> {
|
|
902
|
+
readonly __isDataBinding: true;
|
|
903
|
+
readonly __bindingPath: string;
|
|
904
|
+
readonly __bindingPipes: string[];
|
|
905
|
+
toToken(): string;
|
|
906
|
+
toString(): string;
|
|
907
|
+
valueOf(): string;
|
|
908
|
+
toJSON(): string;
|
|
909
|
+
default(fallback: string | number | boolean): DataBindingField<V>;
|
|
910
|
+
divide(divisor: number): DataBindingField<number>;
|
|
911
|
+
multiply(factor: number): DataBindingField<number>;
|
|
912
|
+
add(offset: number): DataBindingField<number>;
|
|
913
|
+
round(decimals?: number): DataBindingField<number>;
|
|
914
|
+
upper(): DataBindingField<string>;
|
|
915
|
+
lower(): DataBindingField<string>;
|
|
916
|
+
currency(symbol?: string): DataBindingField<string>;
|
|
917
|
+
percent(decimals?: number): DataBindingField<string>;
|
|
918
|
+
ifTruthy(thenValue: string | number, elseValue?: string | number): DataBindingField<string>;
|
|
919
|
+
}
|
|
920
|
+
|
|
921
|
+
export type DataBindingField<T = any> = DataBindingMethods<T> &
|
|
922
|
+
(T extends Array<infer U>
|
|
923
|
+
? { readonly [index: number]: DataBindingField<U> }
|
|
924
|
+
: T extends object
|
|
925
|
+
? { readonly [K in keyof T]-?: DataBindingField<T[K]> }
|
|
926
|
+
: unknown);
|
|
927
|
+
|
|
928
|
+
export type DataBindingProxy<T = Record<string, any>> = DataBindingField<T>;
|
|
929
|
+
|
|
589
930
|
export interface LiveActivityPushTokens {
|
|
590
931
|
/** Token APNs của thiết bị (Device Token 64-hex chars) dùng cho Push Notification / Silent Push */
|
|
591
932
|
devicePushToken: string | null;
|
|
@@ -599,5 +940,234 @@ export interface LiveActivityPushTokens {
|
|
|
599
940
|
|
|
600
941
|
export interface ActiveActivityInfo {
|
|
601
942
|
activityId: string;
|
|
943
|
+
systemActivityId?: string;
|
|
944
|
+
activityState?: 'active' | 'stale' | 'ended' | 'dismissed' | 'expired' | string;
|
|
945
|
+
isStale?: boolean;
|
|
946
|
+
relevanceScore?: number;
|
|
947
|
+
staleTimestamp?: number;
|
|
948
|
+
scheduledEndTimestamp?: number;
|
|
602
949
|
pushToken?: string;
|
|
603
950
|
}
|
|
951
|
+
|
|
952
|
+
/**
|
|
953
|
+
* 📊 Bảng tra cứu năng lực nền tảng (Platform Capability & Fallback Matrix).
|
|
954
|
+
* Cho phép ứng dụng kiểm tra tính năng được hỗ trợ thực tế trên thiết bị đang chạy
|
|
955
|
+
* thay vì phỏng đoán, đảm bảo UI hoạt động ổn định và graceful fallback mượt mà.
|
|
956
|
+
*/
|
|
957
|
+
export interface WidgetCapabilities {
|
|
958
|
+
/** Nền tảng hệ điều hành ('ios' hoặc 'android') */
|
|
959
|
+
platform: 'ios' | 'android';
|
|
960
|
+
/** Phiên bản OS (ví dụ '18.1', '17.2', '14.0' Android API 34) */
|
|
961
|
+
osVersion: string | number;
|
|
962
|
+
/** Hỗ trợ Live Activities trên Lock Screen (iOS 16.1+ / Android 8.0+ Ongoing Notification) */
|
|
963
|
+
supportsLiveActivities: boolean;
|
|
964
|
+
/** Hỗ trợ Dynamic Island (iPhone 14 Pro, 15, 16 series) */
|
|
965
|
+
supportsDynamicIsland: boolean;
|
|
966
|
+
/** Hỗ trợ Android 16+ Live Update thông báo kiểu tiến trình ProgressStyle */
|
|
967
|
+
supportsAndroidLiveUpdates: boolean;
|
|
968
|
+
/** Hỗ trợ ghim tiện ích Home Screen Widgets (iOS 14+ / Android 8.0+) */
|
|
969
|
+
supportsHomeWidgets: boolean;
|
|
970
|
+
/** Hỗ trợ tương tác bấm nút chạy ngầm không mở app (iOS 17+ AppIntent / Android PendingIntent) */
|
|
971
|
+
supportsInteractiveIntents: boolean;
|
|
972
|
+
/** Hỗ trợ dải màu chuyển tiếp Linear / Radial Gradient */
|
|
973
|
+
supportsGradients: boolean;
|
|
974
|
+
/** Hỗ trợ bóng đổ Elevation / Shadow layer */
|
|
975
|
+
supportsShadows: boolean;
|
|
976
|
+
/** Hỗ trợ viền nét đứt Dashed / Dotted Stroke */
|
|
977
|
+
supportsDashedBorders: boolean;
|
|
978
|
+
/** Hỗ trợ tự động co giãn cỡ chữ theo Trợ năng (Accessibility Dynamic Type) */
|
|
979
|
+
supportsDynamicType: boolean;
|
|
980
|
+
/** Hỗ trợ bố cục quốc tế hoá từ phải sang trái (RTL: Arabic, Hebrew, ...) */
|
|
981
|
+
supportsRTL: boolean;
|
|
982
|
+
/** Hỗ trợ chế độ màu Tinted / Accented Widgets (iOS 18+ / Android Material You) */
|
|
983
|
+
supportsTintedMode: boolean;
|
|
984
|
+
/** Hỗ trợ hiệu ứng Odometer số lật (iOS 16+ numericText) */
|
|
985
|
+
supportsNumericAnimation: boolean;
|
|
986
|
+
/** Hỗ trợ lớp Trợ năng phân cấp (Accessibility Fallback Layer: VoiceOver & TalkBack contentDescription) */
|
|
987
|
+
supportsAccessibility: boolean;
|
|
988
|
+
}
|
|
989
|
+
|
|
990
|
+
// ─── 14. UI INTERMEDIATE REPRESENTATION (IR) & SEMANTIC TREE (Phase 2) ────────
|
|
991
|
+
|
|
992
|
+
/**
|
|
993
|
+
* Mục tiêu kết xuất của bộ điều phối Renderer Planner.
|
|
994
|
+
* - 'native_remote_view': Kết xuất thành RemoteViews native (TextView, Button, ProgressBar).
|
|
995
|
+
* - 'canvas_bitmap': Kết xuất qua Canvas 2D Bitmap (Gauge 240°, Equalizer, đồ họa phức tạp).
|
|
996
|
+
* - 'composite': Vùng chứa phức hợp kết hợp cả Native Views và Canvas sub-views.
|
|
997
|
+
*/
|
|
998
|
+
export type RenderPlanTarget = 'native_remote_view' | 'canvas_bitmap' | 'composite';
|
|
999
|
+
|
|
1000
|
+
/**
|
|
1001
|
+
* Kế hoạch kết xuất cho từng Node trong cây UI.
|
|
1002
|
+
*/
|
|
1003
|
+
export interface NodeRenderPlan {
|
|
1004
|
+
id: string;
|
|
1005
|
+
type: LayoutNodeType;
|
|
1006
|
+
target: RenderPlanTarget;
|
|
1007
|
+
reason: string;
|
|
1008
|
+
hasNativeEquivalent: boolean;
|
|
1009
|
+
requiresCanvas: boolean;
|
|
1010
|
+
childrenTargets?: RenderPlanTarget[];
|
|
1011
|
+
}
|
|
1012
|
+
|
|
1013
|
+
/**
|
|
1014
|
+
* ♿ Nút ngữ nghĩa độc lập (Semantic Node) tách biệt hoàn toàn khỏi Renderer.
|
|
1015
|
+
*/
|
|
1016
|
+
export interface SemanticNode {
|
|
1017
|
+
id: string;
|
|
1018
|
+
path: string;
|
|
1019
|
+
type: LayoutNodeType;
|
|
1020
|
+
role: AccessibilityRole;
|
|
1021
|
+
label: string;
|
|
1022
|
+
hint?: string;
|
|
1023
|
+
value?: string | number;
|
|
1024
|
+
interactive: boolean;
|
|
1025
|
+
actionId?: string;
|
|
1026
|
+
deepLink?: string;
|
|
1027
|
+
isDecorative?: boolean;
|
|
1028
|
+
}
|
|
1029
|
+
|
|
1030
|
+
/**
|
|
1031
|
+
* Liên kết trạng thái hai chiều giữa UI và Native Store / JavaScript.
|
|
1032
|
+
*/
|
|
1033
|
+
export interface StateBinding {
|
|
1034
|
+
id: string;
|
|
1035
|
+
actionId: string;
|
|
1036
|
+
bindingType: 'toggle' | 'page' | 'custom';
|
|
1037
|
+
targetKey?: string;
|
|
1038
|
+
initialValue?: any;
|
|
1039
|
+
}
|
|
1040
|
+
|
|
1041
|
+
/**
|
|
1042
|
+
* 🌲 UI Intermediate Representation (Cây đại diện trung gian IR).
|
|
1043
|
+
* Chuẩn hóa toàn bộ cấu trúc UI, Semantic Tree, Kế hoạch kết xuất (Render Plan)
|
|
1044
|
+
* và Liên kết trạng thái (State Bindings) trước khi chuyển giao cho Renderer nền tảng.
|
|
1045
|
+
*/
|
|
1046
|
+
export interface WidgetIR {
|
|
1047
|
+
version: '2.0';
|
|
1048
|
+
timestamp: number;
|
|
1049
|
+
root: LayoutNode;
|
|
1050
|
+
semanticTree: SemanticNode[];
|
|
1051
|
+
semanticSummary: string;
|
|
1052
|
+
renderPlan: {
|
|
1053
|
+
overallStrategy: 'native_first_hybrid' | 'canvas_fallback';
|
|
1054
|
+
nativeNodeCount: number;
|
|
1055
|
+
canvasNodeCount: number;
|
|
1056
|
+
nodes: Record<string, NodeRenderPlan>;
|
|
1057
|
+
};
|
|
1058
|
+
stateBindings: StateBinding[];
|
|
1059
|
+
}
|
|
1060
|
+
|
|
1061
|
+
/**
|
|
1062
|
+
* Danh sách kích thước Widget Family được WidgetKit hỗ trợ trên iOS:
|
|
1063
|
+
*/
|
|
1064
|
+
export type WidgetFamily =
|
|
1065
|
+
| 'systemSmall'
|
|
1066
|
+
| 'systemMedium'
|
|
1067
|
+
| 'systemLarge'
|
|
1068
|
+
| 'systemExtraLarge'
|
|
1069
|
+
| 'accessoryCircular'
|
|
1070
|
+
| 'accessoryRectangular'
|
|
1071
|
+
| 'accessoryInline';
|
|
1072
|
+
|
|
1073
|
+
/**
|
|
1074
|
+
* Cấu hình hệ thống đa ngôn ngữ (i18n) cho Widgets.
|
|
1075
|
+
* Tự động đồng bộ các bản dịch JSON (i18next) sang Apple String Catalog (Localizable.xcstrings / Localizable.strings).
|
|
1076
|
+
*/
|
|
1077
|
+
export interface WidgetsI18nConfig {
|
|
1078
|
+
/**
|
|
1079
|
+
* Đường dẫn tới thư mục chứa các file ngôn ngữ (ví dụ: './src/locales' hoặc './locales').
|
|
1080
|
+
* Hệ thống sẽ tự động quét các file .json như vi.json, en.json, ja.json...
|
|
1081
|
+
*/
|
|
1082
|
+
localesDir?: string;
|
|
1083
|
+
|
|
1084
|
+
/**
|
|
1085
|
+
* Ngôn ngữ nguồn / mặc định (mặc định: 'vi')
|
|
1086
|
+
*/
|
|
1087
|
+
defaultLocale?: string;
|
|
1088
|
+
|
|
1089
|
+
/**
|
|
1090
|
+
* Khai báo bản đồ dịch trực tiếp (inline translations) thay cho hoặc bổ trợ cho file JSON.
|
|
1091
|
+
* Ví dụ: { vi: { 'widgets.title': 'Tiêu đề' }, en: { 'widgets.title': 'Title' } }
|
|
1092
|
+
*/
|
|
1093
|
+
translations?: Record<string, Record<string, any>>;
|
|
1094
|
+
}
|
|
1095
|
+
|
|
1096
|
+
/**
|
|
1097
|
+
* Kiểu chuỗi bản địa hóa đa ngôn ngữ: có thể là 1 string đơn, 1 i18n key hoặc 1 object đa ngôn ngữ.
|
|
1098
|
+
*/
|
|
1099
|
+
export type LocalizedString = string | Record<string, string>;
|
|
1100
|
+
|
|
1101
|
+
/**
|
|
1102
|
+
* Cấu hình một Widget trên Màn hình chính (Home Screen Widget)
|
|
1103
|
+
*/
|
|
1104
|
+
export interface WidgetDefinition {
|
|
1105
|
+
/**
|
|
1106
|
+
* Tên định danh Struct trong Swift (ví dụ: 'DynamicHomeScreenWidget', 'ShiftAttendanceHomeScreenWidget')
|
|
1107
|
+
* Nếu không chỉ định, sẽ tự động sinh từ key (ví dụ: 'shift' -> 'ShiftHomeScreenWidget')
|
|
1108
|
+
*/
|
|
1109
|
+
kind?: string;
|
|
1110
|
+
|
|
1111
|
+
/**
|
|
1112
|
+
* Khóa định danh phân vùng dữ liệu / state của Widget (ví dụ: 'main', 'counter', 'shift', 'pro', 'workspace')
|
|
1113
|
+
* Mặc định là 'main'
|
|
1114
|
+
*/
|
|
1115
|
+
key?: string;
|
|
1116
|
+
|
|
1117
|
+
/**
|
|
1118
|
+
* Tên hiển thị của Widget trong thư viện Widget trên iOS / Android.
|
|
1119
|
+
* Có thể truyền:
|
|
1120
|
+
* - Một i18n key (ví dụ: 'widgets.counter.title')
|
|
1121
|
+
* - Hoặc chuỗi hiển thị trực tiếp
|
|
1122
|
+
* - Hoặc Object đa ngôn ngữ: { vi: '...', en: '...', ja: '...' }
|
|
1123
|
+
*/
|
|
1124
|
+
displayName: LocalizedString;
|
|
1125
|
+
|
|
1126
|
+
/**
|
|
1127
|
+
* Mô tả tính năng của Widget hiển thị cho người dùng khi chọn thêm vào Màn hình chính.
|
|
1128
|
+
* Có thể truyền key i18n, chuỗi trực tiếp hoặc Object đa ngôn ngữ.
|
|
1129
|
+
*/
|
|
1130
|
+
description?: LocalizedString;
|
|
1131
|
+
|
|
1132
|
+
/**
|
|
1133
|
+
* Các kích thước Widget được phép thêm (mặc định hỗ trợ tất cả các cỡ system + accessory)
|
|
1134
|
+
*/
|
|
1135
|
+
supportedFamilies?: WidgetFamily[];
|
|
1136
|
+
|
|
1137
|
+
/**
|
|
1138
|
+
* Có hỗ trợ căn lề StandBy Mode (iOS 17+) không (tự che viền khi ở chế độ cắm sạc ban đêm)
|
|
1139
|
+
*/
|
|
1140
|
+
standbyMargins?: boolean;
|
|
1141
|
+
}
|
|
1142
|
+
|
|
1143
|
+
/**
|
|
1144
|
+
* Cấu hình toàn bộ hệ thống Widgets cho ứng dụng (dùng trong widgets.config.ts)
|
|
1145
|
+
*/
|
|
1146
|
+
export interface WidgetsProjectConfig {
|
|
1147
|
+
/**
|
|
1148
|
+
* Tên bundle Swift (mặc định: 'LiveWidgetsBundle')
|
|
1149
|
+
*/
|
|
1150
|
+
bundleName?: string;
|
|
1151
|
+
|
|
1152
|
+
/**
|
|
1153
|
+
* Cấu hình đa ngôn ngữ i18n (tự động đồng bộ với i18next JSON hoặc Object đa ngôn ngữ)
|
|
1154
|
+
*/
|
|
1155
|
+
i18n?: WidgetsI18nConfig;
|
|
1156
|
+
|
|
1157
|
+
/**
|
|
1158
|
+
* Bật tiện ích Live Activity & Dynamic Island (iOS 16.1+)
|
|
1159
|
+
* Mặc định: true
|
|
1160
|
+
*/
|
|
1161
|
+
liveActivity?: boolean;
|
|
1162
|
+
|
|
1163
|
+
/**
|
|
1164
|
+
* Bật tiện ích Điều khiển Trung tâm Control Center (iOS 18.0+)
|
|
1165
|
+
* Mặc định: true
|
|
1166
|
+
*/
|
|
1167
|
+
controlWidgets?: boolean;
|
|
1168
|
+
|
|
1169
|
+
/**
|
|
1170
|
+
* Danh sách các Widget trên Màn hình chính (Home Screen Widgets)
|
|
1171
|
+
*/
|
|
1172
|
+
widgets: WidgetDefinition[];
|
|
1173
|
+
}
|