react-native-live-widgets 1.2.1 → 1.2.3

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 +37 -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 +889 -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 +1461 -226
  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/types.ts CHANGED
@@ -200,6 +200,8 @@ export interface TextStyle extends ShadowProps, AccessibilityProps {
200
200
  redacted?: boolean;
201
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 */
202
202
  numericAnimation?: boolean;
203
+ /** Cho phép text tự đổi màu theo chế độ StandBy / Tinted iOS 17+ / iOS 18 */
204
+ widgetAccentable?: boolean;
203
205
  }
204
206
 
205
207
  export type StyleProp<T> = T | null | undefined | false | StyleProp<T>[];
@@ -248,8 +250,8 @@ export interface ProgressNode extends BaseNode {
248
250
  startTimestamp?: number;
249
251
  /** Mốc kết thúc (epoch giây) */
250
252
  targetTimestamp?: number;
251
- /** Giá trị cố định từ 0.0 đến 1.0 (nếu không dùng timer) */
252
- 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>;
253
255
 
254
256
  // ── 2. Kiểu dáng hiển thị (Style & Shape) ───────────────────
255
257
  /** 'bar': thanh liền mạch | 'segmented': thanh nhiều chặng | 'circular': vòng tròn % */
@@ -296,9 +298,27 @@ export interface ProgressNode extends BaseNode {
296
298
  /** Có hiển thị chữ phần trăm ở góc không (ví dụ "75%") */
297
299
  showPercentage?: boolean;
298
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;
299
303
  };
300
304
  }
301
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
+
302
322
  export interface ImageNode extends BaseNode {
303
323
  type: 'Image';
304
324
  props: AccessibilityProps & {
@@ -308,12 +328,26 @@ export interface ImageNode extends BaseNode {
308
328
  base64?: string;
309
329
  /** Tên ảnh trong Xcode Assets.xcassets hoặc Android drawable */
310
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;
311
335
  /** Tên icon hệ thống SF Symbols trên iOS (ví dụ 'person.crop.circle.fill', 'flame.fill', 'cart.fill') */
312
- systemName?: string;
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;
313
347
  /** Đường dẫn file cục bộ trong máy */
314
348
  filePath?: string;
315
349
  /** Icon SF Symbol dự phòng khi ảnh mạng chưa tải xong hoặc lỗi */
316
- fallbackSystemName?: string;
350
+ fallbackSystemName?: SFSymbolName;
317
351
  width?: number;
318
352
  height?: number;
319
353
  /** 'fill': phủ kín khung ảnh (crop) | 'fit': vừa khung ảnh */
@@ -434,8 +468,8 @@ export interface DividerNode extends BaseNode {
434
468
  export interface GaugeNode extends BaseNode {
435
469
  type: 'Gauge';
436
470
  props: AccessibilityProps & {
437
- /** Giá trị tiến độ từ 0.0 đến 1.0 */
438
- value: number;
471
+ /** Giá trị tiến độ từ 0.0 đến 1.0 hoặc biểu thức binding */
472
+ value: number | string | DataBindingField<any>;
439
473
  /** Chuỗi hiển thị chính giữa đồng hồ (vd "85%", "120 km/h", "420") */
440
474
  valueText?: string;
441
475
  /** Nhãn phụ bên dưới đồng hồ (vd "KPI", "Kcal", "AQI") */
@@ -454,6 +488,8 @@ export interface GaugeNode extends BaseNode {
454
488
  strokeWidth?: number;
455
489
  /** Tự động ẩn hoặc làm mờ đồng hồ khi màn hình khóa */
456
490
  privacySensitive?: boolean;
491
+ /** Cho phép đồng hồ đổi màu theo StandBy / Tinted iOS 17+ / iOS 18 */
492
+ widgetAccentable?: boolean;
457
493
  };
458
494
  }
459
495
 
@@ -501,7 +537,12 @@ export interface BadgeNode extends BaseNode {
501
537
  type: 'Badge';
502
538
  props: {
503
539
  text: string;
504
- systemName?: string;
540
+ systemName?: SFSymbolName;
541
+ iosSystemName?: SFSymbolName;
542
+ androidSystemName?: MaterialIconName;
543
+ systemNameIos?: SFSymbolName;
544
+ systemNameAndroid?: MaterialIconName;
545
+ materialName?: MaterialIconName;
505
546
  backgroundColor?: string;
506
547
  textColor?: string;
507
548
  borderColor?: string;
@@ -586,14 +627,14 @@ export type LayoutNode =
586
627
  | CustomNode;
587
628
 
588
629
  export interface DynamicIslandConfig {
589
- compactLeading: LayoutNode;
590
- compactTrailing: LayoutNode;
591
- minimal?: LayoutNode;
630
+ compactLeading: LayoutNode | React.ReactNode;
631
+ compactTrailing: LayoutNode | React.ReactNode;
632
+ minimal?: LayoutNode | React.ReactNode;
592
633
  expanded?: {
593
- leading?: LayoutNode;
594
- trailing?: LayoutNode;
595
- bottom?: LayoutNode;
596
- center?: LayoutNode;
634
+ leading?: LayoutNode | React.ReactNode;
635
+ trailing?: LayoutNode | React.ReactNode;
636
+ bottom?: LayoutNode | React.ReactNode;
637
+ center?: LayoutNode | React.ReactNode;
597
638
  };
598
639
  }
599
640
 
@@ -605,14 +646,53 @@ export interface PhaseConfig {
605
646
  alertBody?: string;
606
647
  }
607
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
+
608
671
  export interface StartActivityOptions {
609
672
  activityId: string;
610
673
  lockScreen: LayoutNode;
611
674
  dynamicIsland?: DynamicIslandConfig;
612
675
  phases?: PhaseConfig[];
676
+ /** Epoch timestamp (giây hoặc ms) mà từ thời điểm đó Activity bị coi là cũ (Stale) */
613
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;
614
686
  alertTitle?: string;
615
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';
616
696
  }
617
697
 
618
698
  export interface UpdateActivityOptions {
@@ -620,8 +700,16 @@ export interface UpdateActivityOptions {
620
700
  lockScreen?: LayoutNode;
621
701
  dynamicIsland?: DynamicIslandConfig;
622
702
  staleTimestamp?: number;
703
+ staleLockScreen?: LayoutNode;
704
+ staleDynamicIsland?: DynamicIslandConfig;
705
+ relevanceScore?: number;
706
+ alertConfig?: AlertConfig;
623
707
  alertTitle?: string;
624
708
  alertBody?: string;
709
+ scheduledEndTimestamp?: number;
710
+ autoEndAfterSeconds?: number;
711
+ expiredLockScreen?: LayoutNode;
712
+ expiredDismissalPolicy?: 'immediate' | 'default' | 'afterDate';
625
713
  }
626
714
 
627
715
  export interface EndActivityOptions {
@@ -644,6 +732,10 @@ export interface WidgetSinglePageConfig {
644
732
  small?: LayoutNode;
645
733
  medium?: LayoutNode;
646
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;
647
739
  /** Màn hình khóa iOS 16+: Tiện ích hình chữ nhật bo góc dưới đồng hồ */
648
740
  accessoryRectangular?: LayoutNode;
649
741
  /** Màn hình khóa iOS 16+: Tiện ích ô tròn nhỏ dưới đồng hồ (Gauge / Circular Progress / Icon) */
@@ -652,6 +744,20 @@ export interface WidgetSinglePageConfig {
652
744
  accessoryInline?: LayoutNode;
653
745
  }
654
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
+
655
761
  export interface WidgetLayoutConfig extends WidgetSinglePageConfig {
656
762
  /**
657
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).
@@ -681,6 +787,8 @@ export interface WidgetTimelineEntry {
681
787
  date: number | string;
682
788
  /** Cấu hình layout tại mốc thời gian tương ứng */
683
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>;
684
792
  }
685
793
 
686
794
  export interface WidgetTimelineConfig {
@@ -704,19 +812,121 @@ export interface WidgetConfigOption {
704
812
  icon?: string;
705
813
  }
706
814
 
707
- export interface WidgetRemoteConfig {
708
- /** URL API mà Widget Extension sẽ tự gọi ngầm (kể cả khi người dùng đã kill App chính) */
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 */
709
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 {
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;
710
850
  /** HTTP Method (mặc định 'GET') */
711
- method?: 'GET' | 'POST';
851
+ method?: 'GET' | 'POST' | 'PUT';
852
+ /** Payload gửi kèm cho POST / PUT */
853
+ body?: string | Record<string, any>;
712
854
  /** Headers xác thực (ví dụ { Authorization: 'Bearer ...' }) */
713
855
  headers?: Record<string, string>;
714
- /** Chu kỳ tự động gọi lại API tính bằng phút (mặc định 15 phút) */
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
+ */
715
881
  refreshIntervalMinutes?: number;
716
882
  /** Alias ngắn gọn cho refreshIntervalMinutes */
717
883
  intervalMinutes?: number;
718
884
  }
719
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
+
720
930
  export interface LiveActivityPushTokens {
721
931
  /** Token APNs của thiết bị (Device Token 64-hex chars) dùng cho Push Notification / Silent Push */
722
932
  devicePushToken: string | null;
@@ -730,6 +940,12 @@ export interface LiveActivityPushTokens {
730
940
 
731
941
  export interface ActiveActivityInfo {
732
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;
733
949
  pushToken?: string;
734
950
  }
735
951
 
@@ -841,3 +1057,117 @@ export interface WidgetIR {
841
1057
  };
842
1058
  stateBindings: StateBinding[];
843
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
+ }