react-native-live-widgets 1.2.1 → 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 (79) hide show
  1. package/CHANGELOG.md +27 -0
  2. package/README.md +89 -49
  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 +86 -13
  9. package/android/src/main/java/com/reactnativeliveactivity/storage/DynamicWidgetImageCache.kt +53 -0
  10. package/android/src/main/java/com/reactnativeliveactivity/storage/DynamicWidgetStateStore.kt +647 -104
  11. package/android/src/main/java/com/reactnativeliveactivity/widgets/DynamicHomeScreenWidgetProvider.kt +3 -1
  12. package/android/src/main/java/com/reactnativeliveactivity/widgets/DynamicQuickSettingsTileService.kt +120 -0
  13. package/app.plugin.js +36 -0
  14. package/assets/MaterialIcons.json +2236 -0
  15. package/cli/codegen.js +789 -0
  16. package/cli/setup.js +323 -63
  17. package/docs/EXPO-GUIDE-EN.md +21 -3
  18. package/docs/EXPO-GUIDE-VI.md +21 -3
  19. package/docs/GUIDE-EN.md +203 -21
  20. package/docs/GUIDE-VI.md +207 -22
  21. package/docs/index.html +1328 -211
  22. package/docs/llms-full.txt +15 -0
  23. package/docs/llms.txt +16 -7
  24. package/ios/Bridge/LiveActivityModule.swift +333 -44
  25. package/ios/Intents/DynamicWidgetActionIntent.swift +57 -2
  26. package/ios/Models/DynamicLayoutModels.swift +114 -4
  27. package/ios/Renderer/DynamicNodeView.swift +15 -6
  28. package/ios/Storage/DynamicWidgetStateStore.swift +649 -38
  29. package/ios/Widgets/DynamicControlWidget.swift +63 -0
  30. package/ios/Widgets/DynamicHomeScreenWidget.swift +99 -26
  31. package/ios/Widgets/DynamicLiveActivityWidget.swift +25 -4
  32. package/lib/builder.d.ts +50 -7
  33. package/lib/builder.d.ts.map +1 -1
  34. package/lib/builder.js +326 -18
  35. package/lib/builder.js.map +1 -1
  36. package/lib/hooks.d.ts +13 -9
  37. package/lib/hooks.d.ts.map +1 -1
  38. package/lib/hooks.js +70 -12
  39. package/lib/hooks.js.map +1 -1
  40. package/lib/index.d.ts +80 -7
  41. package/lib/index.d.ts.map +1 -1
  42. package/lib/index.js +303 -59
  43. package/lib/index.js.map +1 -1
  44. package/lib/ir.d.ts.map +1 -1
  45. package/lib/ir.js +9 -2
  46. package/lib/ir.js.map +1 -1
  47. package/lib/jsx.d.ts +11 -7
  48. package/lib/jsx.d.ts.map +1 -1
  49. package/lib/jsx.js +50 -13
  50. package/lib/jsx.js.map +1 -1
  51. package/lib/material-icons.generated.d.ts +8 -0
  52. package/lib/material-icons.generated.d.ts.map +1 -0
  53. package/lib/material-icons.generated.js +9 -0
  54. package/lib/material-icons.generated.js.map +1 -0
  55. package/lib/preview.d.ts +11 -4
  56. package/lib/preview.d.ts.map +1 -1
  57. package/lib/preview.js +150 -82
  58. package/lib/preview.js.map +1 -1
  59. package/lib/sf-symbols.generated.d.ts +8 -0
  60. package/lib/sf-symbols.generated.d.ts.map +1 -0
  61. package/lib/sf-symbols.generated.js +9 -0
  62. package/lib/sf-symbols.generated.js.map +1 -0
  63. package/lib/types.d.ts +302 -18
  64. package/lib/types.d.ts.map +1 -1
  65. package/package.json +6 -2
  66. package/scripts/build.js +98 -0
  67. package/scripts/generate-material-icons.js +93 -0
  68. package/scripts/generate-sf-symbols.js +95 -0
  69. package/scripts/release.js +115 -0
  70. package/scripts/test-ir-semantic.js +314 -0
  71. package/src/builder.ts +382 -24
  72. package/src/hooks.ts +88 -12
  73. package/src/index.ts +319 -56
  74. package/src/ir.ts +8 -2
  75. package/src/jsx.tsx +69 -21
  76. package/src/material-icons.generated.ts +3844 -0
  77. package/src/preview.tsx +235 -81
  78. package/src/sf-symbols.generated.ts +9533 -0
  79. package/src/types.ts +348 -18
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,
@@ -24,6 +27,7 @@ import {
24
27
  TimerNode,
25
28
  ToggleNode,
26
29
  VStackNode,
30
+ WidgetDataPipeOptions,
27
31
  ZStackNode,
28
32
  ZStackProps,
29
33
  } from './types';
@@ -31,6 +35,270 @@ import { registerAction } from './dispatcher';
31
35
 
32
36
  let autoActionCounter = 0;
33
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
+
34
302
  export function flattenStyle<T extends object>(...styles: StyleProp<T>[]): T | undefined {
35
303
  let merged: any = undefined;
36
304
 
@@ -83,6 +351,12 @@ function normalizeProps<P extends object>(props?: P): P | undefined {
83
351
  if (!props) return undefined;
84
352
  const p = { ...props } as any;
85
353
 
354
+ for (const key of Object.keys(p)) {
355
+ if (isDataBinding(p[key])) {
356
+ p[key] = p[key].toToken();
357
+ }
358
+ }
359
+
86
360
  // Bo góc alias
87
361
  if (p.cornerRadius !== undefined && p.borderRadius === undefined) {
88
362
  p.borderRadius = p.cornerRadius;
@@ -93,6 +367,17 @@ function normalizeProps<P extends object>(props?: P): P | undefined {
93
367
  p.spacing = p.gap;
94
368
  }
95
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
+
96
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
97
382
  if (p.gradient && Array.isArray(p.gradient.colors) && p.gradient.colors.length > 0 && !p.backgroundColor) {
98
383
  p.backgroundColor = p.gradient.colors[0];
@@ -179,14 +464,14 @@ export const UI = {
179
464
  },
180
465
 
181
466
  Text: (
182
- text: string,
467
+ text: string | DataBindingField<any>,
183
468
  ...styles: StyleProp<TextStyle>[]
184
469
  ): TextNode => {
185
470
  const merged = flattenStyle(...styles);
186
471
  return {
187
472
  type: 'Text',
188
473
  props: normalizeProps<TextNodeProps>({
189
- text,
474
+ text: String(resolveBindingValue(text) ?? ''),
190
475
  ...(merged || {}),
191
476
  })!,
192
477
  };
@@ -212,14 +497,18 @@ export const UI = {
212
497
  }),
213
498
 
214
499
  Progress: (
215
- valueOrOptions: number | ProgressNode['props'],
500
+ valueOrOptions: number | string | DataBindingField<any> | ProgressNode['props'],
216
501
  options?: Omit<ProgressNode['props'], 'value'>
217
502
  ): ProgressNode => {
218
- if (typeof valueOrOptions === 'number') {
503
+ if (
504
+ typeof valueOrOptions === 'number' ||
505
+ typeof valueOrOptions === 'string' ||
506
+ isDataBinding(valueOrOptions)
507
+ ) {
219
508
  return {
220
509
  type: 'Progress',
221
510
  props: normalizeProps({
222
- value: valueOrOptions,
511
+ value: resolveBindingValue(valueOrOptions),
223
512
  ...options,
224
513
  })!,
225
514
  };
@@ -231,20 +520,24 @@ export const UI = {
231
520
  },
232
521
 
233
522
  Image: (
234
- urlOrOptions: string | ImageNode['props'],
523
+ urlOrOptions: string | DataBindingField<any> | ImageNode['props'],
235
524
  options?: Omit<ImageNode['props'], 'url'>
236
525
  ): ImageNode => {
237
- if (typeof urlOrOptions === 'string') {
238
- const isHttp = urlOrOptions.startsWith('http://') || urlOrOptions.startsWith('https://');
239
- 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/');
240
533
  return {
241
534
  type: 'Image',
242
535
  props: normalizeProps({
243
536
  ...(isHttp
244
- ? { url: urlOrOptions }
537
+ ? { url: resolved }
245
538
  : isBase64
246
- ? { base64: urlOrOptions }
247
- : { systemName: urlOrOptions }),
539
+ ? { base64: resolved }
540
+ : { systemName: resolved }),
248
541
  ...options,
249
542
  })!,
250
543
  };
@@ -261,10 +554,10 @@ export const UI = {
261
554
  }),
262
555
 
263
556
  Button: (
264
- titleOrProps: string | ButtonNode['props'],
557
+ titleOrProps: string | DataBindingField<any> | ButtonNode['props'],
265
558
  options?: Omit<ButtonNode['props'], 'title'>
266
559
  ): ButtonNode => {
267
- if (typeof titleOrProps === 'object' && titleOrProps !== null) {
560
+ if (typeof titleOrProps === 'object' && titleOrProps !== null && !isDataBinding(titleOrProps)) {
268
561
  const normalized = normalizeProps(titleOrProps)!;
269
562
  if (normalized.onPress && !normalized.actionId) {
270
563
  autoActionCounter += 1;
@@ -291,7 +584,7 @@ export const UI = {
291
584
  return {
292
585
  type: 'Button',
293
586
  props: normalizeProps({
294
- title: titleOrProps,
587
+ title: String(resolveBindingValue(titleOrProps)),
295
588
  ...options,
296
589
  actionId: finalActionId,
297
590
  })!,
@@ -351,21 +644,25 @@ export const UI = {
351
644
  }),
352
645
 
353
646
  Gauge: (
354
- valueOrOptions: number | GaugeNode['props'],
647
+ valueOrOptions: number | string | DataBindingField<any> | GaugeNode['props'],
355
648
  options?: Omit<GaugeNode['props'], 'value'>
356
649
  ): GaugeNode => {
357
- if (typeof valueOrOptions === 'number') {
650
+ if (
651
+ typeof valueOrOptions === 'number' ||
652
+ typeof valueOrOptions === 'string' ||
653
+ isDataBinding(valueOrOptions)
654
+ ) {
358
655
  return {
359
656
  type: 'Gauge',
360
- props: {
361
- value: valueOrOptions,
657
+ props: normalizeProps({
658
+ value: resolveBindingValue(valueOrOptions),
362
659
  ...options,
363
- },
660
+ })!,
364
661
  };
365
662
  }
366
663
  return {
367
664
  type: 'Gauge',
368
- props: valueOrOptions,
665
+ props: normalizeProps(valueOrOptions)!,
369
666
  };
370
667
  },
371
668
 
@@ -409,14 +706,14 @@ export const UI = {
409
706
  },
410
707
 
411
708
  Badge: (
412
- textOrOptions: string | BadgeNode['props'],
709
+ textOrOptions: string | DataBindingField<any> | BadgeNode['props'],
413
710
  options?: Omit<BadgeNode['props'], 'text'>
414
711
  ): BadgeNode => {
415
- if (typeof textOrOptions === 'string') {
712
+ if (typeof textOrOptions === 'string' || isDataBinding(textOrOptions)) {
416
713
  return {
417
714
  type: 'Badge',
418
715
  props: normalizeProps({
419
- text: textOrOptions,
716
+ text: String(resolveBindingValue(textOrOptions)),
420
717
  ...options,
421
718
  })!,
422
719
  };
@@ -471,4 +768,65 @@ export const UI = {
471
768
  ...options,
472
769
  },
473
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,
474
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
+ }