react-native-live-widgets 1.2.0 → 1.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (87) hide show
  1. package/CHANGELOG.md +34 -0
  2. package/README.md +129 -50
  3. package/android/src/main/AndroidManifest.xml +12 -0
  4. package/android/src/main/assets/fonts/MaterialIcons-Regular.ttf +0 -0
  5. package/android/src/main/java/com/reactnativeliveactivity/bridge/LiveActivityModule.kt +61 -1
  6. package/android/src/main/java/com/reactnativeliveactivity/liveactivity/LiveActivityNotifier.kt +153 -17
  7. package/android/src/main/java/com/reactnativeliveactivity/liveactivity/LiveActivityReceiver.kt +1 -1
  8. package/android/src/main/java/com/reactnativeliveactivity/renderer/DynamicWidgetCanvasRenderer.kt +529 -59
  9. package/android/src/main/java/com/reactnativeliveactivity/storage/DynamicWidgetImageCache.kt +53 -0
  10. package/android/src/main/java/com/reactnativeliveactivity/storage/DynamicWidgetStateStore.kt +684 -83
  11. package/android/src/main/java/com/reactnativeliveactivity/widgets/DynamicHomeScreenWidgetProvider.kt +129 -57
  12. package/android/src/main/java/com/reactnativeliveactivity/widgets/DynamicQuickSettingsTileService.kt +120 -0
  13. package/android/src/main/res/layout/rn_live_widget_hit_zone.xml +16 -0
  14. package/android/src/main/res/layout/rn_live_widget_host.xml +16 -87
  15. package/app.plugin.js +36 -0
  16. package/assets/MaterialIcons.json +2236 -0
  17. package/cli/codegen.js +789 -0
  18. package/cli/setup.js +323 -63
  19. package/docs/EXPO-GUIDE-EN.md +21 -3
  20. package/docs/EXPO-GUIDE-VI.md +21 -3
  21. package/docs/GUIDE-EN.md +444 -21
  22. package/docs/GUIDE-VI.md +473 -22
  23. package/docs/index.html +2263 -265
  24. package/docs/llms-full.txt +41 -0
  25. package/docs/llms.txt +24 -7
  26. package/ios/Bridge/LiveActivityModule.swift +333 -44
  27. package/ios/Intents/DynamicWidgetActionIntent.swift +57 -2
  28. package/ios/Models/DynamicLayoutModels.swift +120 -5
  29. package/ios/Renderer/DynamicNodeView.swift +184 -20
  30. package/ios/Storage/DynamicWidgetStateStore.swift +649 -38
  31. package/ios/Widgets/DynamicControlWidget.swift +63 -0
  32. package/ios/Widgets/DynamicHomeScreenWidget.swift +104 -26
  33. package/ios/Widgets/DynamicLiveActivityWidget.swift +25 -4
  34. package/lib/builder.d.ts +50 -7
  35. package/lib/builder.d.ts.map +1 -1
  36. package/lib/builder.js +391 -29
  37. package/lib/builder.js.map +1 -1
  38. package/lib/dispatcher.js +16 -10
  39. package/lib/dispatcher.js.map +1 -1
  40. package/lib/hooks.d.ts +13 -9
  41. package/lib/hooks.d.ts.map +1 -1
  42. package/lib/hooks.js +105 -42
  43. package/lib/hooks.js.map +1 -1
  44. package/lib/index.d.ts +96 -8
  45. package/lib/index.d.ts.map +1 -1
  46. package/lib/index.js +415 -97
  47. package/lib/index.js.map +1 -1
  48. package/lib/ir.d.ts +15 -0
  49. package/lib/ir.d.ts.map +1 -0
  50. package/lib/ir.js +386 -0
  51. package/lib/ir.js.map +1 -0
  52. package/lib/jsx.d.ts +19 -7
  53. package/lib/jsx.d.ts.map +1 -1
  54. package/lib/jsx.js +179 -95
  55. package/lib/jsx.js.map +1 -1
  56. package/lib/material-icons.generated.d.ts +8 -0
  57. package/lib/material-icons.generated.d.ts.map +1 -0
  58. package/lib/material-icons.generated.js +9 -0
  59. package/lib/material-icons.generated.js.map +1 -0
  60. package/lib/preview.d.ts +11 -27
  61. package/lib/preview.d.ts.map +1 -1
  62. package/lib/preview.js +456 -119
  63. package/lib/preview.js.map +1 -1
  64. package/lib/sf-symbols.generated.d.ts +8 -0
  65. package/lib/sf-symbols.generated.d.ts.map +1 -0
  66. package/lib/sf-symbols.generated.js +9 -0
  67. package/lib/sf-symbols.generated.js.map +1 -0
  68. package/lib/types.d.ts +506 -30
  69. package/lib/types.d.ts.map +1 -1
  70. package/lib/types.js +2 -1
  71. package/lib/types.js.map +1 -1
  72. package/package.json +7 -2
  73. package/scripts/build.js +98 -0
  74. package/scripts/generate-material-icons.js +93 -0
  75. package/scripts/generate-sf-symbols.js +95 -0
  76. package/scripts/release.js +115 -0
  77. package/scripts/test-ir-semantic.js +314 -0
  78. package/src/builder.ts +439 -26
  79. package/src/hooks.ts +88 -12
  80. package/src/index.ts +385 -57
  81. package/src/ir.ts +436 -0
  82. package/src/jsx.tsx +99 -21
  83. package/src/material-icons.generated.ts +3844 -0
  84. package/src/preview.tsx +533 -55
  85. package/src/react-native-env.d.ts +1 -0
  86. package/src/sf-symbols.generated.ts +9533 -0
  87. package/src/types.ts +601 -31
package/src/builder.ts CHANGED
@@ -3,7 +3,10 @@ import {
3
3
  ButtonNode,
4
4
  ChartNode,
5
5
  ContainerProps,
6
+ ControlWidgetConfig,
6
7
  CustomNode,
8
+ DataBindingField,
9
+ DataBindingProxy,
7
10
  DividerNode,
8
11
  EqualizerNode,
9
12
  EqualizerProps,
@@ -19,10 +22,12 @@ import {
19
22
  SpacerNode,
20
23
  StyleProp,
21
24
  TextNode,
25
+ TextNodeProps,
22
26
  TextStyle,
23
27
  TimerNode,
24
28
  ToggleNode,
25
29
  VStackNode,
30
+ WidgetDataPipeOptions,
26
31
  ZStackNode,
27
32
  ZStackProps,
28
33
  } from './types';
@@ -30,6 +35,270 @@ import { registerAction } from './dispatcher';
30
35
 
31
36
  let autoActionCounter = 0;
32
37
 
38
+ export function isDataBinding(value: any): value is DataBindingField<any> {
39
+ return Boolean(
40
+ value &&
41
+ (typeof value === 'object' || typeof value === 'function') &&
42
+ (value as any).__isDataBinding === true
43
+ );
44
+ }
45
+
46
+ export function resolveBindingValue(value: any): any {
47
+ if (isDataBinding(value)) {
48
+ return value.toToken();
49
+ }
50
+ return value;
51
+ }
52
+
53
+ function buildPipeToken(path: string, pipes: string[]): string {
54
+ return pipes.length > 0 ? `{{${path}|${pipes.join('|')}}}` : `{{${path}}}`;
55
+ }
56
+
57
+ function convertPipeOptions(pipes?: WidgetDataPipeOptions): string[] {
58
+ if (!pipes) return [];
59
+ const out: string[] = [];
60
+ if (pipes.default !== undefined) out.push(`default:${pipes.default}`);
61
+ if (pipes.divide !== undefined) out.push(`divide:${pipes.divide}`);
62
+ if (pipes.multiply !== undefined) out.push(`multiply:${pipes.multiply}`);
63
+ if (pipes.add !== undefined) out.push(`add:${pipes.add}`);
64
+ if (pipes.round !== undefined) out.push(`round:${pipes.round}`);
65
+ if (pipes.upper) out.push('upper');
66
+ if (pipes.lower) out.push('lower');
67
+ if (pipes.currency !== undefined) out.push(`currency:${pipes.currency}`);
68
+ if (pipes.percent !== undefined) out.push(`percent:${pipes.percent}`);
69
+ if (pipes.ifTruthy) {
70
+ const [thenVal, elseVal = ''] = pipes.ifTruthy;
71
+ out.push(`if:${thenVal}:${elseVal}`);
72
+ }
73
+ return out;
74
+ }
75
+
76
+ function createBindingField(
77
+ path: string,
78
+ pipes: string[] = [],
79
+ defaultsMap?: Record<string, string>
80
+ ): DataBindingField<any> {
81
+ const effectivePipes = [...pipes];
82
+ if (
83
+ defaultsMap &&
84
+ defaultsMap[path] !== undefined &&
85
+ !effectivePipes.some((p) => p.startsWith('default:'))
86
+ ) {
87
+ effectivePipes.unshift(`default:${defaultsMap[path]}`);
88
+ }
89
+
90
+ const token = buildPipeToken(path, effectivePipes);
91
+ const target: Record<string | symbol, any> = {
92
+ __isDataBinding: true,
93
+ __bindingPath: path,
94
+ __bindingPipes: effectivePipes,
95
+ toToken: () => token,
96
+ toString: () => token,
97
+ valueOf: () => token,
98
+ toJSON: () => token,
99
+ [Symbol.toPrimitive]: () => token,
100
+ default: (fallback: string | number | boolean) =>
101
+ createBindingField(path, [...pipes, `default:${fallback}`], defaultsMap),
102
+ divide: (divisor: number) =>
103
+ createBindingField(path, [...pipes, `divide:${divisor}`], defaultsMap),
104
+ multiply: (factor: number) =>
105
+ createBindingField(path, [...pipes, `multiply:${factor}`], defaultsMap),
106
+ add: (offset: number) =>
107
+ createBindingField(path, [...pipes, `add:${offset}`], defaultsMap),
108
+ round: (decimals = 0) =>
109
+ createBindingField(path, [...pipes, `round:${decimals}`], defaultsMap),
110
+ upper: () => createBindingField(path, [...pipes, 'upper'], defaultsMap),
111
+ lower: () => createBindingField(path, [...pipes, 'lower'], defaultsMap),
112
+ currency: (symbol = '₫') =>
113
+ createBindingField(path, [...pipes, `currency:${symbol}`], defaultsMap),
114
+ percent: (decimals = 0) =>
115
+ createBindingField(path, [...pipes, `percent:${decimals}`], defaultsMap),
116
+ ifTruthy: (thenValue: string | number, elseValue: string | number = '') =>
117
+ createBindingField(path, [...pipes, `if:${thenValue}:${elseValue}`], defaultsMap),
118
+ };
119
+
120
+ return new Proxy(target, {
121
+ get(obj, prop) {
122
+ if (prop in obj || typeof prop === 'symbol') {
123
+ return obj[prop];
124
+ }
125
+ // Tránh đánh lừa Promise (.then) hoặc React element checks ($$typeof)
126
+ if (prop === 'then' || prop === 'catch' || prop === 'finally' || prop === '$$typeof') {
127
+ return undefined;
128
+ }
129
+ const nextPath = path ? `${path}.${String(prop)}` : String(prop);
130
+ return createBindingField(nextPath, [], defaultsMap);
131
+ },
132
+ }) as DataBindingField<any>;
133
+ }
134
+
135
+ /**
136
+ * Tạo đối tượng Data Binding có cấu trúc & gợi ý kiểu TypeScript để nhúng trực tiếp vào JSX/DSL Widget.
137
+ */
138
+ export function createDataBinding<T extends Record<string, any> = Record<string, any>>(options?: {
139
+ defaults?: Record<string, any>;
140
+ prefix?: string;
141
+ }): DataBindingProxy<T> {
142
+ const defaultsMap = options?.defaults ? flattenDataObject(options.defaults) : undefined;
143
+ return createBindingField(options?.prefix || '', [], defaultsMap) as DataBindingProxy<T>;
144
+ }
145
+
146
+ /**
147
+ * Làm phẳng đệ quy JSON lồng nhau thành các đường dẫn dot-notation (`user.name`, `items.0.title`).
148
+ */
149
+ export function flattenDataObject(
150
+ obj: any,
151
+ prefix = '',
152
+ out: Record<string, string> = {}
153
+ ): Record<string, string> {
154
+ if (obj === null || obj === undefined) return out;
155
+ if (Array.isArray(obj)) {
156
+ obj.forEach((item, idx) => {
157
+ const nextKey = prefix ? `${prefix}.${idx}` : String(idx);
158
+ if (item !== null && typeof item === 'object') {
159
+ flattenDataObject(item, nextKey, out);
160
+ } else if (item !== undefined && item !== null) {
161
+ out[nextKey] = String(item);
162
+ }
163
+ });
164
+ return out;
165
+ }
166
+ if (typeof obj === 'object') {
167
+ for (const [k, v] of Object.entries(obj)) {
168
+ const nextKey = prefix ? `${prefix}.${k}` : k;
169
+ if (v !== null && typeof v === 'object') {
170
+ flattenDataObject(v, nextKey, out);
171
+ } else if (v !== undefined && v !== null) {
172
+ out[nextKey] = String(v);
173
+ }
174
+ }
175
+ } else if (prefix) {
176
+ out[prefix] = String(obj);
177
+ }
178
+ return out;
179
+ }
180
+
181
+ function sanitizeVariableValue(rawValue: string | undefined): string | undefined {
182
+ if (rawValue === undefined || rawValue === null) return rawValue;
183
+ const trimmed = String(rawValue).trim();
184
+ const m = trimmed.match(/^\{\{([^{}|]+)\}\}$/);
185
+ return m ? m[1].trim() : rawValue;
186
+ }
187
+
188
+ /**
189
+ * Thực thi các phép biến đổi Pipe trên chuỗi giá trị thô (đồng bộ 1:1 với Swift & Kotlin).
190
+ */
191
+ export function evaluateTemplatePipe(rawValue: string | undefined, pipes: string[]): string {
192
+ const cleaned = sanitizeVariableValue(rawValue);
193
+ let current = cleaned !== undefined && cleaned !== null ? String(cleaned) : '';
194
+
195
+ for (const rawPipe of pipes) {
196
+ const colonIdx = rawPipe.indexOf(':');
197
+ const op = colonIdx >= 0 ? rawPipe.slice(0, colonIdx).trim() : rawPipe.trim();
198
+ const arg = colonIdx >= 0 ? rawPipe.slice(colonIdx + 1) : '';
199
+
200
+ switch (op) {
201
+ case 'default': {
202
+ if (current === '') {
203
+ current = arg;
204
+ }
205
+ break;
206
+ }
207
+ case 'divide': {
208
+ const num = parseFloat(current);
209
+ const div = parseFloat(arg);
210
+ if (!Number.isNaN(num) && !Number.isNaN(div) && div !== 0) {
211
+ current = String(num / div);
212
+ }
213
+ break;
214
+ }
215
+ case 'multiply': {
216
+ const num = parseFloat(current);
217
+ const mul = parseFloat(arg);
218
+ if (!Number.isNaN(num) && !Number.isNaN(mul)) {
219
+ current = String(num * mul);
220
+ }
221
+ break;
222
+ }
223
+ case 'add': {
224
+ const num = parseFloat(current);
225
+ const offset = parseFloat(arg);
226
+ if (!Number.isNaN(num) && !Number.isNaN(offset)) {
227
+ current = String(num + offset);
228
+ }
229
+ break;
230
+ }
231
+ case 'round': {
232
+ const num = parseFloat(current);
233
+ const decimals = Math.max(0, parseInt(arg || '0', 10) || 0);
234
+ if (!Number.isNaN(num)) {
235
+ current = decimals === 0 ? String(Math.round(num)) : num.toFixed(decimals);
236
+ }
237
+ break;
238
+ }
239
+ case 'upper': {
240
+ current = current.toUpperCase();
241
+ break;
242
+ }
243
+ case 'lower': {
244
+ current = current.toLowerCase();
245
+ break;
246
+ }
247
+ case 'currency': {
248
+ const num = parseFloat(current);
249
+ const symbol = arg || '₫';
250
+ if (!Number.isNaN(num)) {
251
+ current = `${Math.round(num).toLocaleString('en-US')}${symbol}`;
252
+ }
253
+ break;
254
+ }
255
+ case 'percent': {
256
+ const num = parseFloat(current);
257
+ const decimals = Math.max(0, parseInt(arg || '0', 10) || 0);
258
+ if (!Number.isNaN(num)) {
259
+ current = `${decimals === 0 ? Math.round(num) : num.toFixed(decimals)}%`;
260
+ }
261
+ break;
262
+ }
263
+ case 'if': {
264
+ const splitIdx = arg.indexOf(':');
265
+ const thenVal = splitIdx >= 0 ? arg.slice(0, splitIdx) : arg;
266
+ const elseVal = splitIdx >= 0 ? arg.slice(splitIdx + 1) : '';
267
+ const lower = current.trim().toLowerCase();
268
+ const isTruthy =
269
+ current.trim() !== '' && lower !== 'false' && lower !== '0' && lower !== 'null';
270
+ current = isTruthy ? thenVal : elseVal;
271
+ break;
272
+ }
273
+ default:
274
+ break;
275
+ }
276
+ }
277
+ return current;
278
+ }
279
+
280
+ /**
281
+ * Thay thế toàn bộ token `{{path|pipe1|pipe2}}` trong chuỗi theo bản đồ biến (hỗ trợ cả JSON lồng nhau).
282
+ */
283
+ export function resolveTemplateString(template: string, vars: Record<string, any>): string {
284
+ if (!template || !template.includes('{{')) return template;
285
+ const flatVars = flattenDataObject(vars);
286
+ return template.replace(/\{\{([^}]+)\}\}/g, (match, expr) => {
287
+ const parts = String(expr).split('|');
288
+ const pathKey = parts[0].trim();
289
+ const pipes = parts.slice(1);
290
+ const hasKey = Object.prototype.hasOwnProperty.call(flatVars, pathKey);
291
+ if (!hasKey && pipes.length === 0) {
292
+ return match;
293
+ }
294
+ const rawVal = hasKey ? flatVars[pathKey] : undefined;
295
+ if (!hasKey && !pipes.some((p) => p.trim().startsWith('default:') || p.trim().startsWith('if:'))) {
296
+ return match;
297
+ }
298
+ return evaluateTemplatePipe(rawVal, pipes);
299
+ });
300
+ }
301
+
33
302
  export function flattenStyle<T extends object>(...styles: StyleProp<T>[]): T | undefined {
34
303
  let merged: any = undefined;
35
304
 
@@ -64,12 +333,83 @@ function isLayoutNode(item: any): item is LayoutNode {
64
333
  return item && typeof item === 'object' && typeof item.type === 'string';
65
334
  }
66
335
 
336
+ const TYPOGRAPHY_DEFAULTS: Record<string, { fontSize: number; fontWeight: any }> = {
337
+ largeTitle: { fontSize: 34, fontWeight: 'bold' },
338
+ title1: { fontSize: 28, fontWeight: 'bold' },
339
+ title2: { fontSize: 22, fontWeight: 'bold' },
340
+ title3: { fontSize: 20, fontWeight: 'semibold' },
341
+ headline: { fontSize: 17, fontWeight: 'semibold' },
342
+ body: { fontSize: 17, fontWeight: 'regular' },
343
+ callout: { fontSize: 16, fontWeight: 'regular' },
344
+ subheadline: { fontSize: 15, fontWeight: 'regular' },
345
+ footnote: { fontSize: 13, fontWeight: 'regular' },
346
+ caption1: { fontSize: 12, fontWeight: 'regular' },
347
+ caption2: { fontSize: 11, fontWeight: 'regular' },
348
+ };
349
+
67
350
  function normalizeProps<P extends object>(props?: P): P | undefined {
68
351
  if (!props) return undefined;
69
352
  const p = { ...props } as any;
353
+
354
+ for (const key of Object.keys(p)) {
355
+ if (isDataBinding(p[key])) {
356
+ p[key] = p[key].toToken();
357
+ }
358
+ }
359
+
360
+ // Bo góc alias
70
361
  if (p.cornerRadius !== undefined && p.borderRadius === undefined) {
71
362
  p.borderRadius = p.cornerRadius;
72
363
  }
364
+
365
+ // Spacing / Gap alias chuẩn React Native
366
+ if (p.gap !== undefined && p.spacing === undefined) {
367
+ p.spacing = p.gap;
368
+ }
369
+
370
+ // Alias icon đa nền tảng (iOS vs Android)
371
+ if (p.systemNameIos !== undefined && p.iosSystemName === undefined) {
372
+ p.iosSystemName = p.systemNameIos;
373
+ }
374
+ if (p.systemNameAndroid !== undefined && p.androidSystemName === undefined) {
375
+ p.androidSystemName = p.systemNameAndroid;
376
+ }
377
+ if (p.materialName !== undefined && p.androidSystemName === undefined) {
378
+ p.androidSystemName = p.materialName;
379
+ }
380
+
381
+ // Graceful Fallback cho Gradient: nếu nền tảng/OS không hỗ trợ gradient, tự lấy màu đầu tiên làm backgroundColor
382
+ if (p.gradient && Array.isArray(p.gradient.colors) && p.gradient.colors.length > 0 && !p.backgroundColor) {
383
+ p.backgroundColor = p.gradient.colors[0];
384
+ }
385
+
386
+ // Typography scale chuẩn
387
+ if (p.typography && TYPOGRAPHY_DEFAULTS[p.typography]) {
388
+ const typo = TYPOGRAPHY_DEFAULTS[p.typography];
389
+ if (p.fontSize === undefined) p.fontSize = typo.fontSize;
390
+ if (p.fontWeight === undefined) p.fontWeight = typo.fontWeight;
391
+ }
392
+
393
+ // Trợ năng / Accessibility Semantics Fallback (Phase 1):
394
+ if (p.accessible === undefined) {
395
+ if (p.text !== undefined || p.title !== undefined || p.actionId !== undefined) {
396
+ p.accessible = true;
397
+ }
398
+ }
399
+
400
+ if (p.accessibilityLabel === undefined) {
401
+ if (p.text !== undefined) p.accessibilityLabel = String(p.text);
402
+ else if (p.title !== undefined) p.accessibilityLabel = String(p.title);
403
+ }
404
+
405
+ if (p.accessibilityRole === undefined) {
406
+ if (p.title !== undefined || p.actionId !== undefined) {
407
+ p.accessibilityRole = 'button';
408
+ } else if (p.typography && (p.typography.startsWith('title') || p.typography === 'largeTitle' || p.typography === 'headline')) {
409
+ p.accessibilityRole = 'header';
410
+ }
411
+ }
412
+
73
413
  return p as P;
74
414
  }
75
415
 
@@ -124,16 +464,16 @@ export const UI = {
124
464
  },
125
465
 
126
466
  Text: (
127
- text: string,
467
+ text: string | DataBindingField<any>,
128
468
  ...styles: StyleProp<TextStyle>[]
129
469
  ): TextNode => {
130
470
  const merged = flattenStyle(...styles);
131
471
  return {
132
472
  type: 'Text',
133
- props: {
134
- text,
473
+ props: normalizeProps<TextNodeProps>({
474
+ text: String(resolveBindingValue(text) ?? ''),
135
475
  ...(merged || {}),
136
- },
476
+ })!,
137
477
  };
138
478
  },
139
479
 
@@ -157,14 +497,18 @@ export const UI = {
157
497
  }),
158
498
 
159
499
  Progress: (
160
- valueOrOptions: number | ProgressNode['props'],
500
+ valueOrOptions: number | string | DataBindingField<any> | ProgressNode['props'],
161
501
  options?: Omit<ProgressNode['props'], 'value'>
162
502
  ): ProgressNode => {
163
- if (typeof valueOrOptions === 'number') {
503
+ if (
504
+ typeof valueOrOptions === 'number' ||
505
+ typeof valueOrOptions === 'string' ||
506
+ isDataBinding(valueOrOptions)
507
+ ) {
164
508
  return {
165
509
  type: 'Progress',
166
510
  props: normalizeProps({
167
- value: valueOrOptions,
511
+ value: resolveBindingValue(valueOrOptions),
168
512
  ...options,
169
513
  })!,
170
514
  };
@@ -176,20 +520,24 @@ export const UI = {
176
520
  },
177
521
 
178
522
  Image: (
179
- urlOrOptions: string | ImageNode['props'],
523
+ urlOrOptions: string | DataBindingField<any> | ImageNode['props'],
180
524
  options?: Omit<ImageNode['props'], 'url'>
181
525
  ): ImageNode => {
182
- if (typeof urlOrOptions === 'string') {
183
- const isHttp = urlOrOptions.startsWith('http://') || urlOrOptions.startsWith('https://');
184
- const isBase64 = urlOrOptions.startsWith('data:image/');
526
+ if (typeof urlOrOptions === 'string' || isDataBinding(urlOrOptions)) {
527
+ const resolved = String(resolveBindingValue(urlOrOptions));
528
+ const isHttp =
529
+ resolved.startsWith('http://') ||
530
+ resolved.startsWith('https://') ||
531
+ resolved.includes('{{');
532
+ const isBase64 = resolved.startsWith('data:image/');
185
533
  return {
186
534
  type: 'Image',
187
535
  props: normalizeProps({
188
536
  ...(isHttp
189
- ? { url: urlOrOptions }
537
+ ? { url: resolved }
190
538
  : isBase64
191
- ? { base64: urlOrOptions }
192
- : { systemName: urlOrOptions }),
539
+ ? { base64: resolved }
540
+ : { systemName: resolved }),
193
541
  ...options,
194
542
  })!,
195
543
  };
@@ -206,10 +554,10 @@ export const UI = {
206
554
  }),
207
555
 
208
556
  Button: (
209
- titleOrProps: string | ButtonNode['props'],
557
+ titleOrProps: string | DataBindingField<any> | ButtonNode['props'],
210
558
  options?: Omit<ButtonNode['props'], 'title'>
211
559
  ): ButtonNode => {
212
- if (typeof titleOrProps === 'object' && titleOrProps !== null) {
560
+ if (typeof titleOrProps === 'object' && titleOrProps !== null && !isDataBinding(titleOrProps)) {
213
561
  const normalized = normalizeProps(titleOrProps)!;
214
562
  if (normalized.onPress && !normalized.actionId) {
215
563
  autoActionCounter += 1;
@@ -236,7 +584,7 @@ export const UI = {
236
584
  return {
237
585
  type: 'Button',
238
586
  props: normalizeProps({
239
- title: titleOrProps,
587
+ title: String(resolveBindingValue(titleOrProps)),
240
588
  ...options,
241
589
  actionId: finalActionId,
242
590
  })!,
@@ -296,21 +644,25 @@ export const UI = {
296
644
  }),
297
645
 
298
646
  Gauge: (
299
- valueOrOptions: number | GaugeNode['props'],
647
+ valueOrOptions: number | string | DataBindingField<any> | GaugeNode['props'],
300
648
  options?: Omit<GaugeNode['props'], 'value'>
301
649
  ): GaugeNode => {
302
- if (typeof valueOrOptions === 'number') {
650
+ if (
651
+ typeof valueOrOptions === 'number' ||
652
+ typeof valueOrOptions === 'string' ||
653
+ isDataBinding(valueOrOptions)
654
+ ) {
303
655
  return {
304
656
  type: 'Gauge',
305
- props: {
306
- value: valueOrOptions,
657
+ props: normalizeProps({
658
+ value: resolveBindingValue(valueOrOptions),
307
659
  ...options,
308
- },
660
+ })!,
309
661
  };
310
662
  }
311
663
  return {
312
664
  type: 'Gauge',
313
- props: valueOrOptions,
665
+ props: normalizeProps(valueOrOptions)!,
314
666
  };
315
667
  },
316
668
 
@@ -354,14 +706,14 @@ export const UI = {
354
706
  },
355
707
 
356
708
  Badge: (
357
- textOrOptions: string | BadgeNode['props'],
709
+ textOrOptions: string | DataBindingField<any> | BadgeNode['props'],
358
710
  options?: Omit<BadgeNode['props'], 'text'>
359
711
  ): BadgeNode => {
360
- if (typeof textOrOptions === 'string') {
712
+ if (typeof textOrOptions === 'string' || isDataBinding(textOrOptions)) {
361
713
  return {
362
714
  type: 'Badge',
363
715
  props: normalizeProps({
364
- text: textOrOptions,
716
+ text: String(resolveBindingValue(textOrOptions)),
365
717
  ...options,
366
718
  })!,
367
719
  };
@@ -416,4 +768,65 @@ export const UI = {
416
768
  ...options,
417
769
  },
418
770
  }),
771
+
772
+ /**
773
+ * Cấu hình Control Button cho iOS 18+ Control Center / Action Button & Android Quick Settings Tile.
774
+ */
775
+ ControlButton: (
776
+ options: Omit<ControlWidgetConfig, 'type' | 'actionId'> & {
777
+ actionId?: string;
778
+ onPress?: (payload?: any) => Promise<any> | any;
779
+ }
780
+ ): ControlWidgetConfig => buildControlConfig('button', options),
781
+
782
+ /**
783
+ * Cấu hình Control Toggle 2 trạng thái cho iOS 18+ Control Center & Android Quick Settings Tile.
784
+ */
785
+ ControlToggle: (
786
+ options: Omit<ControlWidgetConfig, 'type' | 'actionId'> & {
787
+ actionId?: string;
788
+ onPress?: (payload?: any) => Promise<any> | any;
789
+ }
790
+ ): ControlWidgetConfig => buildControlConfig('toggle', options),
791
+
792
+ /**
793
+ * Tạo biểu thức Data Binding chuỗi token (`{{path|pipe1|pipe2}}`) dùng với Background Data Engine 2.0.
794
+ */
795
+ bind: (path: string, pipes?: WidgetDataPipeOptions): string =>
796
+ buildPipeToken(path, convertPipeOptions(pipes)),
797
+
798
+ /**
799
+ * Tạo Proxy Data Binding có cấu trúc & gợi ý kiểu TypeScript (`data.user.name`, `data.attendance.progress.divide(100)`).
800
+ */
801
+ createDataBinding,
419
802
  };
803
+
804
+ function buildControlConfig(
805
+ type: 'button' | 'toggle',
806
+ options: Omit<ControlWidgetConfig, 'type' | 'actionId'> & {
807
+ actionId?: string;
808
+ onPress?: (payload?: any) => Promise<any> | any;
809
+ }
810
+ ): ControlWidgetConfig {
811
+ const { onPress, actionId, ...rest } = options;
812
+ let resolvedActionId = actionId;
813
+ if (!resolvedActionId) {
814
+ autoActionCounter += 1;
815
+ resolvedActionId =
816
+ type === 'toggle'
817
+ ? `toggle:control_${Date.now()}_${autoActionCounter}`
818
+ : `control_${Date.now()}_${autoActionCounter}`;
819
+ } else if (type === 'toggle' && !resolvedActionId.startsWith('toggle:')) {
820
+ resolvedActionId = `toggle:${resolvedActionId}`;
821
+ }
822
+
823
+ if (onPress) {
824
+ registerAction(resolvedActionId, onPress);
825
+ }
826
+
827
+ return {
828
+ ...rest,
829
+ type,
830
+ actionId: resolvedActionId,
831
+ };
832
+ }