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/cli/setup.js CHANGED
@@ -21,6 +21,26 @@ const packageJsonPath = path.join(projectRoot, 'package.json');
21
21
 
22
22
  // Parse CLI arguments
23
23
  const args = process.argv.slice(2);
24
+
25
+ // Support subcommands: codegen / generate
26
+ if (args[0] === 'codegen' || args[0] === 'generate') {
27
+ const { runCodegen } = require('./codegen');
28
+ let configArg = null;
29
+ for (let i = 1; i < args.length; i++) {
30
+ if (args[i] === '--config' && args[i + 1]) {
31
+ configArg = args[i + 1];
32
+ break;
33
+ }
34
+ }
35
+ try {
36
+ runCodegen(projectRoot, configArg);
37
+ process.exit(0);
38
+ } catch (error) {
39
+ console.error(`\n❌ [Codegen Error]: ${error.message}\n`);
40
+ process.exit(1);
41
+ }
42
+ }
43
+
24
44
  let customAppGroup = null;
25
45
  for (let i = 0; i < args.length; i++) {
26
46
  if (args[i] === '--group' && args[i + 1]) {
@@ -29,7 +49,7 @@ for (let i = 0; i < args.length; i++) {
29
49
  }
30
50
  }
31
51
 
32
- console.log('\n🚀 [react-native-live-widgets] Bắt đầu thiết lập tự động...');
52
+ console.log('\n🚀 [react-native-live-widgets] Starting automated setup...');
33
53
 
34
54
  // 1. Detect project name and bundle ID
35
55
  let pkgName = 'MyApp';
@@ -40,15 +60,66 @@ if (fs.existsSync(packageJsonPath)) {
40
60
  } catch (_e) {}
41
61
  }
42
62
 
43
- let appGroup = customAppGroup || `group.com.${pkgName.toLowerCase().replace(/[^a-z0-9]/g, '')}`;
44
- console.log(`📦 App Group được sử dụng: ${appGroup}`);
63
+ let detectedAppName = pkgName;
64
+ if (fs.existsSync(iosDir)) {
65
+ try {
66
+ const xcodeProjects = fs.readdirSync(iosDir).filter((file) => file.endsWith('.xcodeproj'));
67
+ if (xcodeProjects.length > 0) {
68
+ detectedAppName = xcodeProjects[0].replace('.xcodeproj', '');
69
+ }
70
+ } catch (_e) {}
71
+ }
45
72
 
46
- // 2. Handle Expo project (app.json)
47
- const isExpo = fs.existsSync(appJsonPath);
48
- if (isExpo) {
73
+ let appGroup = customAppGroup || `group.com.${detectedAppName.toLowerCase().replace(/[^a-z0-9]/g, '')}`;
74
+ console.log(`📦 App Group configured: ${appGroup}`);
75
+
76
+ // 2. Ensure app.json exists and contains "name" and "displayName"
77
+ let isExpo = false;
78
+ let appJson = null;
79
+
80
+ if (!fs.existsSync(appJsonPath)) {
81
+ appJson = {
82
+ name: detectedAppName,
83
+ displayName: detectedAppName,
84
+ };
85
+ fs.writeFileSync(appJsonPath, JSON.stringify(appJson, null, 2) + '\n', 'utf8');
86
+ console.log(`✅ Created app.json with name: "${detectedAppName}"`);
87
+ } else {
88
+ try {
89
+ appJson = JSON.parse(fs.readFileSync(appJsonPath, 'utf8'));
90
+ if (appJson && typeof appJson.expo === 'object') {
91
+ isExpo = true;
92
+ }
93
+
94
+ let appJsonChanged = false;
95
+ if (!appJson.name) {
96
+ appJson.name = detectedAppName;
97
+ appJsonChanged = true;
98
+ }
99
+ if (!appJson.displayName) {
100
+ appJson.displayName = appJson.name || detectedAppName;
101
+ appJsonChanged = true;
102
+ }
103
+ if (appJsonChanged) {
104
+ fs.writeFileSync(appJsonPath, JSON.stringify(appJson, null, 2) + '\n', 'utf8');
105
+ console.log(`✅ Updated app.json with name: "${appJson.name}"`);
106
+ }
107
+ } catch (_e) {}
108
+ }
109
+
110
+ if (!isExpo && fs.existsSync(packageJsonPath)) {
111
+ try {
112
+ const pkgJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
113
+ const allDeps = { ...(pkgJson.dependencies || {}), ...(pkgJson.devDependencies || {}) };
114
+ if (allDeps['expo']) {
115
+ isExpo = true;
116
+ }
117
+ } catch (_e) {}
118
+ }
119
+
120
+ if (isExpo && appJson) {
49
121
  try {
50
- console.log('📱 Phát hiện dự án Expo. Đang cập nhật app.json...');
51
- const appJson = JSON.parse(fs.readFileSync(appJsonPath, 'utf8'));
122
+ console.log('📱 Expo project detected. Updating app.json...');
52
123
  if (!appJson.expo) appJson.expo = {};
53
124
  if (!appJson.expo.plugins) appJson.expo.plugins = [];
54
125
 
@@ -68,21 +139,97 @@ if (isExpo) {
68
139
 
69
140
  if (existingIndex >= 0) {
70
141
  appJson.expo.plugins[existingIndex] = pluginConfig;
71
- console.log('ℹ️ Đã cập nhật plugin react-native-live-widgets trong app.json');
142
+ console.log('ℹ️ Updated react-native-live-widgets plugin in app.json');
72
143
  } else {
73
144
  appJson.expo.plugins.push(pluginConfig);
74
- console.log('✅ Đã thêm plugin react-native-live-widgets vào app.json');
145
+ console.log('✅ Added react-native-live-widgets plugin to app.json');
75
146
  }
76
147
 
77
148
  fs.writeFileSync(appJsonPath, JSON.stringify(appJson, null, 2), 'utf8');
78
149
  } catch (e) {
79
- console.warn('⚠️ Không thể cập nhật app.json:', e.message);
150
+ console.warn('⚠️ Failed to update app.json:', e.message);
151
+ }
152
+ }
153
+
154
+ // 3. Configure Entrypoint file (index.js / index.ts / index.tsx)
155
+ const entryCandidates = ['index.js', 'index.ts', 'index.tsx', 'index.jsx'];
156
+ let entryFile = null;
157
+ for (const cand of entryCandidates) {
158
+ const full = path.join(projectRoot, cand);
159
+ if (fs.existsSync(full)) {
160
+ entryFile = full;
161
+ break;
80
162
  }
81
163
  }
82
164
 
83
- // 3. Configure iOS Native Project (if ios/ folder exists)
165
+ if (entryFile) {
166
+ try {
167
+ let content = fs.readFileSync(entryFile, 'utf8');
168
+ let entryModified = false;
169
+
170
+ // Check if AppRegistry uses appName and import from app.json is missing
171
+ const hasAppJsonImport = /from\s+['"]\.\/app(?:\.json)?['"]/.test(content);
172
+ const usesAppName = /\bappName\b/.test(content);
173
+ if (usesAppName && !hasAppJsonImport) {
174
+ content = "import { name as appName } from './app.json';\n" + content;
175
+ entryModified = true;
176
+ }
177
+
178
+ // Check if LiveActivity.registerBackgroundActionHandler() is already called
179
+ const hasBackgroundHandler = content.includes('registerBackgroundActionHandler');
180
+ if (!hasBackgroundHandler) {
181
+ const liveWidgetsImportRegex = /from\s+['"]react-native-live-widgets['"]/;
182
+ if (!liveWidgetsImportRegex.test(content)) {
183
+ const lines = content.split('\n');
184
+ let lastImportLineIdx = -1;
185
+ for (let i = 0; i < lines.length; i++) {
186
+ if (lines[i].trim().startsWith('import ')) {
187
+ lastImportLineIdx = i;
188
+ }
189
+ }
190
+
191
+ const importLine = "import { LiveActivity } from 'react-native-live-widgets';";
192
+ if (lastImportLineIdx !== -1) {
193
+ lines.splice(lastImportLineIdx + 1, 0, importLine);
194
+ } else {
195
+ lines.unshift(importLine);
196
+ }
197
+ content = lines.join('\n');
198
+ } else if (!/import\s+[^;]*\bLiveActivity\b[^;]*from\s+['"]react-native-live-widgets['"]/.test(content)) {
199
+ content = content.replace(
200
+ /(import\s*\{)([^}]*)(\}\s*from\s*['"]react-native-live-widgets['"])/,
201
+ '$1 LiveActivity, $2$3'
202
+ );
203
+ }
204
+
205
+ // Add LiveActivity.registerBackgroundActionHandler(); before AppRegistry.registerComponent or registerRootComponent
206
+ const handlerCall = '\nLiveActivity.registerBackgroundActionHandler();\n';
207
+ const mountIndex = content.indexOf('AppRegistry.registerComponent') !== -1
208
+ ? content.indexOf('AppRegistry.registerComponent')
209
+ : content.indexOf('registerRootComponent');
210
+
211
+ if (mountIndex !== -1) {
212
+ content = content.slice(0, mountIndex) + handlerCall + content.slice(mountIndex);
213
+ } else {
214
+ content += handlerCall;
215
+ }
216
+ entryModified = true;
217
+ }
218
+
219
+ if (entryModified) {
220
+ fs.writeFileSync(entryFile, content, 'utf8');
221
+ console.log(`✅ Configured ${path.basename(entryFile)} with LiveActivity.registerBackgroundActionHandler()`);
222
+ } else {
223
+ console.log(`ℹ️ Entrypoint ${path.basename(entryFile)} is already properly configured`);
224
+ }
225
+ } catch (err) {
226
+ console.warn(`⚠️ Failed to inspect/update entrypoint:`, err.message);
227
+ }
228
+ }
229
+
230
+ // 4. Configure iOS Native Project (if ios/ folder exists)
84
231
  if (fs.existsSync(iosDir)) {
85
- console.log('\n🍎 Đang cấu hình iOS (Info.plist, Entitlements, WidgetExtension Target)...');
232
+ console.log('\n🍎 Configuring iOS (Info.plist, Entitlements, WidgetExtension Target)...');
86
233
 
87
234
  try {
88
235
  const xcodeProjects = fs.readdirSync(iosDir).filter((file) => file.endsWith('.xcodeproj'));
@@ -102,9 +249,9 @@ if (fs.existsSync(iosDir)) {
102
249
  '<dict>\n\t<key>NSSupportsLiveActivities</key>\n\t<true/>\n\t<key>NSSupportsLiveActivitiesFrequentUpdates</key>\n\t<true/>'
103
250
  );
104
251
  fs.writeFileSync(infoPlistPath, plistContent, 'utf8');
105
- console.log(`✅ Đã thêm NSSupportsLiveActivities vào ${appName}/Info.plist`);
252
+ console.log(`✅ Added NSSupportsLiveActivities to ${appName}/Info.plist`);
106
253
  } else {
107
- console.log(`ℹ️ NSSupportsLiveActivities đã tồn tại trong ${appName}/Info.plist`);
254
+ console.log(`ℹ️ NSSupportsLiveActivities already exists in ${appName}/Info.plist`);
108
255
  }
109
256
  }
110
257
 
@@ -123,7 +270,7 @@ if (fs.existsSync(iosDir)) {
123
270
  `;
124
271
  if (!fs.existsSync(entitlementsPath)) {
125
272
  fs.writeFileSync(entitlementsPath, entitlementsXml, 'utf8');
126
- console.log(`✅ Đã tạo ${appName}.entitlements với App Group: ${appGroup}`);
273
+ console.log(`✅ Created ${appName}.entitlements with App Group: ${appGroup}`);
127
274
  } else {
128
275
  let content = fs.readFileSync(entitlementsPath, 'utf8');
129
276
  if (!content.includes(appGroup)) {
@@ -139,7 +286,7 @@ if (fs.existsSync(iosDir)) {
139
286
  );
140
287
  }
141
288
  fs.writeFileSync(entitlementsPath, content, 'utf8');
142
- console.log(`✅ Đã thêm App Group vào ${appName}.entitlements`);
289
+ console.log(`✅ Added App Group to ${appName}.entitlements`);
143
290
  }
144
291
  }
145
292
 
@@ -159,8 +306,8 @@ import SwiftUI
159
306
  import react_native_live_widgets
160
307
  #endif
161
308
 
162
- /// Bundle mở rộng hỗ trợ cả Live Activity (Lock Screen & Dynamic Island)
163
- /// và Home Screen Widgets (Màn hình chính iOS 16.1 -> iOS 17/18/27+)
309
+ /// Bundle extension supporting both Live Activities (Dynamic Island / Lock Screen)
310
+ /// and Home Screen Widgets (iOS 16.1 -> iOS 17/18+)
164
311
  @main
165
312
  struct LiveWidgetsBundle: WidgetBundle {
166
313
  var body: some Widget {
@@ -169,24 +316,30 @@ struct LiveWidgetsBundle: WidgetBundle {
169
316
  DynamicLiveActivityWidget()
170
317
  }
171
318
 
172
- // 2. Tiện ích chính (Dynamic / Đang chọn trong App)
319
+ // 2. Primary dynamic Home Screen widget
173
320
  DynamicHomeScreenWidget()
174
321
 
175
- // 3. Tiện ích Bộ đếm tương tác (Interactive TS Counter)
322
+ // 3. Interactive TypeScript counter widget
176
323
  InteractiveCounterHomeScreenWidget()
177
324
 
178
- // 4. Tiện ích Bảo mật & Tính năng Pro (Core 2.0)
325
+ // 4. Pro Features & Security widget
179
326
  ProFeaturesHomeScreenWidget()
180
327
 
181
- // 5. Tiện ích Chấm công & Ca làm việc (Shift Attendance)
328
+ // 5. Shift Attendance widget
182
329
  ShiftAttendanceHomeScreenWidget()
183
330
 
184
- // 6. Tiện ích Không gian làm việc đa trang (Multi-Page Workspace)
331
+ // 6. Multi-page Workspace widget
185
332
  MultiPageHomeScreenWidget()
333
+
334
+ // 7. iOS 18+ Interactive Control Center Widgets
335
+ if #available(iOS 18.0, *) {
336
+ DynamicControlWidget()
337
+ DynamicControlToggleWidget()
338
+ }
186
339
  }
187
340
  }
188
341
 
189
- // ── 1. TIỆN ÍCH CHÍNH (ĐỒNG BỘ THEO MẪU ĐANG CHỌN) ──
342
+ // ── 1. PRIMARY DYNAMIC WIDGET ──
190
343
  struct DynamicHomeScreenWidget: Widget {
191
344
  let kind: String = "DynamicHomeScreenWidget"
192
345
 
@@ -194,13 +347,13 @@ struct DynamicHomeScreenWidget: Widget {
194
347
  StaticConfiguration(kind: kind, provider: DynamicWidgetProvider(widgetKey: "main")) { entry in
195
348
  DynamicHomeScreenWidgetView(entry: entry)
196
349
  }
197
- .configurationDisplayName("Tiện ích Live Widgets")
198
- .description("Tự động đồng bộ và hiển thị theo mẫu giao diện bạn chọn trong ứng dụng.")
350
+ .configurationDisplayName("Live Widgets")
351
+ .description("Automatically syncs and displays the dynamic layout selected in app.")
199
352
  .supportedFamilies(commonFamilies)
200
353
  }
201
354
  }
202
355
 
203
- // ── 2. TIỆN ÍCH BỘ ĐẾM TƯƠNG TÁC TYPESCRIPT ──
356
+ // ── 2. INTERACTIVE COUNTER WIDGET ──
204
357
  struct InteractiveCounterHomeScreenWidget: Widget {
205
358
  let kind: String = "InteractiveCounterHomeScreenWidget"
206
359
 
@@ -208,13 +361,13 @@ struct InteractiveCounterHomeScreenWidget: Widget {
208
361
  StaticConfiguration(kind: kind, provider: DynamicWidgetProvider(widgetKey: "counter")) { entry in
209
362
  DynamicHomeScreenWidgetView(entry: entry)
210
363
  }
211
- .configurationDisplayName("Bộ đếm tương tác (TS)")
212
- .description("Bấm nút [+] hoặc [-] để kích hoạt trực tiếp hàm logic TypeScript.")
364
+ .configurationDisplayName("Interactive Counter (TS)")
365
+ .description("Tap [+] or [-] to trigger TypeScript logic directly.")
213
366
  .supportedFamilies(commonFamilies)
214
367
  }
215
368
  }
216
369
 
217
- // ── 3. TIỆN ÍCH BẢO MẬT & KPI PRO (CORE 2.0) ──
370
+ // ── 3. PRO FEATURES & SECURITY WIDGET ──
218
371
  struct ProFeaturesHomeScreenWidget: Widget {
219
372
  let kind: String = "ProFeaturesHomeScreenWidget"
220
373
 
@@ -222,13 +375,14 @@ struct ProFeaturesHomeScreenWidget: Widget {
222
375
  StaticConfiguration(kind: kind, provider: DynamicWidgetProvider(widgetKey: "pro")) { entry in
223
376
  DynamicHomeScreenWidgetView(entry: entry)
224
377
  }
225
- .configurationDisplayName("Bảo mật & KPI Pro")
226
- .description("Tự che số khi khoá máy (Privacy Sensitive) và hỗ trợ chế độ StandBy.")
378
+ .configurationDisplayName("Security & KPI Pro")
379
+ .description("Redacts sensitive data when locked and supports StandBy mode.")
227
380
  .supportedFamilies(commonFamilies)
381
+ .applyStandByMargins()
228
382
  }
229
383
  }
230
384
 
231
- // ── 4. TIỆN ÍCH CHẤM CÔNG & CA LÀM VIỆC ──
385
+ // ── 4. SHIFT ATTENDANCE WIDGET ──
232
386
  struct ShiftAttendanceHomeScreenWidget: Widget {
233
387
  let kind: String = "ShiftAttendanceHomeScreenWidget"
234
388
 
@@ -236,13 +390,13 @@ struct ShiftAttendanceHomeScreenWidget: Widget {
236
390
  StaticConfiguration(kind: kind, provider: DynamicWidgetProvider(widgetKey: "shift")) { entry in
237
391
  DynamicHomeScreenWidgetView(entry: entry)
238
392
  }
239
- .configurationDisplayName("Chấm công & Ca làm việc")
240
- .description("Theo dõi giờ vào làm, thời gian tan ca và thanh tiến trình công việc.")
393
+ .configurationDisplayName("Shift & Attendance")
394
+ .description("Track clock-in time, shift end, and work progress bar.")
241
395
  .supportedFamilies(commonFamilies)
242
396
  }
243
397
  }
244
398
 
245
- // ── 5. TIỆN ÍCH KHÔNG GIAN ĐA TRANG (MULTI-PAGE) ──
399
+ // ── 5. MULTI-PAGE WORKSPACE WIDGET ──
246
400
  struct MultiPageHomeScreenWidget: Widget {
247
401
  let kind: String = "MultiPageHomeScreenWidget"
248
402
 
@@ -250,14 +404,14 @@ struct MultiPageHomeScreenWidget: Widget {
250
404
  StaticConfiguration(kind: kind, provider: DynamicWidgetProvider(widgetKey: "workspace")) { entry in
251
405
  DynamicHomeScreenWidgetView(entry: entry)
252
406
  }
253
- .configurationDisplayName("Không gian đa trang")
254
- .description("Chuyển đổi qua lại giữa Ca làm, Công việc và OKRs ngay trên mặt Widget.")
407
+ .configurationDisplayName("Multi-Page Workspace")
408
+ .description("Switch between Shifts, Tasks, and OKRs directly on the widget.")
255
409
  .supportedFamilies(commonFamilies)
256
410
  }
257
411
  }
258
412
 
259
413
  private var commonFamilies: [WidgetFamily] {
260
- var list: [WidgetFamily] = [.systemSmall, .systemMedium, .systemLarge]
414
+ var list: [WidgetFamily] = [.systemSmall, .systemMedium, .systemLarge, .systemExtraLarge]
261
415
  if #available(iOS 16.0, *) {
262
416
  list.append(contentsOf: [.accessoryRectangular, .accessoryCircular, .accessoryInline])
263
417
  }
@@ -265,7 +419,7 @@ private var commonFamilies: [WidgetFamily] {
265
419
  }
266
420
  `;
267
421
  fs.writeFileSync(widgetBundlePath, bundleCode, 'utf8');
268
- console.log('✅ Đã tạo template: ios/LiveWidgetsExtension/LiveWidgetsBundle.swift');
422
+ console.log('✅ Created template: ios/LiveWidgetsExtension/LiveWidgetsBundle.swift');
269
423
  }
270
424
 
271
425
  // Create extension Info.plist
@@ -302,14 +456,14 @@ private var commonFamilies: [WidgetFamily] {
302
456
  </plist>
303
457
  `;
304
458
  fs.writeFileSync(widgetInfoPlist, extPlistCode, 'utf8');
305
- console.log('✅ Đã tạo Info.plist cho Widget Extension');
459
+ console.log('✅ Created Info.plist for Widget Extension');
306
460
  }
307
461
 
308
462
  // Create extension Entitlements
309
463
  const widgetEntitlementsPath = path.join(widgetTargetDir, 'LiveWidgetsExtension.entitlements');
310
464
  if (!fs.existsSync(widgetEntitlementsPath)) {
311
465
  fs.writeFileSync(widgetEntitlementsPath, entitlementsXml, 'utf8');
312
- console.log('✅ Đã tạo LiveWidgetsExtension.entitlements với App Group');
466
+ console.log('✅ Created LiveWidgetsExtension.entitlements with App Group');
313
467
  }
314
468
 
315
469
  // Copy shared widget Swift files from library
@@ -324,7 +478,7 @@ private var commonFamilies: [WidgetFamily] {
324
478
  }
325
479
  }
326
480
  }
327
- console.log('✅ Đã copy các Swift models và renderers vào LiveWidgetsExtension/Shared/');
481
+ console.log('✅ Copied Swift models and renderers into LiveWidgetsExtension/Shared/');
328
482
 
329
483
  // D. Configure Xcode Project (project.pbxproj) via 'xcode' module
330
484
  let xcode;
@@ -354,15 +508,15 @@ private var commonFamilies: [WidgetFamily] {
354
508
  }
355
509
 
356
510
  if (!targetExists) {
357
- console.log('➕ Đang tạo Xcode Target LiveWidgetsExtension...');
511
+ console.log('➕ Creating Xcode Target LiveWidgetsExtension...');
358
512
  const newTarget = myProj.addTarget(targetName, 'app_extension', targetName);
359
513
 
360
- // Tạo các Build Phases riêng biệt cho Extension Target
514
+ // Create separate Build Phases for the Extension Target
361
515
  myProj.addBuildPhase([], 'PBXSourcesBuildPhase', 'Sources', newTarget.uuid);
362
516
  myProj.addBuildPhase([], 'PBXFrameworksBuildPhase', 'Frameworks', newTarget.uuid);
363
517
  myProj.addBuildPhase([], 'PBXResourcesBuildPhase', 'Resources', newTarget.uuid);
364
518
 
365
- // Thêm các file Swift CHỈ vào Sources của Extension Target (tránh xung đột @main với AppDelegate)
519
+ // Add Swift files ONLY to Sources of Extension Target (prevents @main conflict with AppDelegate)
366
520
  const filesToAdd = [
367
521
  'LiveWidgetsExtension/LiveWidgetsBundle.swift',
368
522
  ...fs.readdirSync(widgetSharedDir).filter(f => f.endsWith('.swift')).map(f => `LiveWidgetsExtension/Shared/${f}`)
@@ -408,9 +562,9 @@ private var commonFamilies: [WidgetFamily] {
408
562
  }
409
563
 
410
564
  fs.writeFileSync(pbxprojPath, myProj.writeSync(), 'utf8');
411
- console.log('✅ Đã nhúng LiveWidgetsExtension vào project.pbxproj thành công!');
565
+ console.log('✅ Successfully embedded LiveWidgetsExtension in project.pbxproj!');
412
566
  } else {
413
- console.log('ℹ️ LiveWidgetsExtension target đã tồn tại trong Xcode project.');
567
+ console.log('ℹ️ LiveWidgetsExtension target already exists in Xcode project.');
414
568
  }
415
569
  }
416
570
 
@@ -424,31 +578,31 @@ private var commonFamilies: [WidgetFamily] {
424
578
  `target '${appName}' do\n pod 'react-native-live-widgets', :path => '../node_modules/react-native-live-widgets'`
425
579
  );
426
580
  fs.writeFileSync(podfilePath, podContent, 'utf8');
427
- console.log(`✅ Đã thêm pod 'react-native-live-widgets' vào Podfile`);
581
+ console.log(`✅ Added pod 'react-native-live-widgets' to Podfile`);
428
582
  }
429
583
  }
430
584
 
431
585
  // F. Run pod install
432
586
  try {
433
- console.log('🔄 Đang chạy pod install...');
587
+ console.log('🔄 Running pod install...');
434
588
  execSync('pod install', { cwd: iosDir, stdio: 'inherit' });
435
- console.log('✅ pod install hoàn tất!');
589
+ console.log('✅ pod install completed successfully!');
436
590
  } catch (_e) {
437
- console.warn('⚠️ Vui lòng chạy "cd ios && pod install" thủ công.');
591
+ console.warn('⚠️ Please run "cd ios && pod install" manually.');
438
592
  }
439
593
  }
440
594
  } catch (e) {
441
- console.warn('⚠️ Lỗi khi cấu hình iOS:', e.message);
595
+ console.warn('⚠️ Error configuring iOS:', e.message);
442
596
  }
443
597
  } else if (isExpo) {
444
- console.log('\n💡 Gợi ý: Thư mục ios/ chưa được tạo. Sau khi cấu hình app.json xong, bạn chỉ cần chạy:');
598
+ console.log('\n💡 Tip: ios/ directory not found. After configuring app.json, simply run:');
445
599
  console.log('👉 npx expo prebuild');
446
- console.log('👉 npx react-native-live-widgets init (để tự động liên kết Xcode target)');
600
+ console.log('👉 npx react-native-live-widgets init (to link Xcode target automatically)');
447
601
  }
448
602
 
449
- // 4. Configure Android Native Project (if android/ folder exists)
603
+ // 5. Configure Android Native Project (if android/ folder exists)
450
604
  if (fs.existsSync(androidDir)) {
451
- console.log('\n🤖 Đang kiểm tra cấu hình Android...');
605
+ console.log('\n🤖 Verifying Android configuration...');
452
606
  const manifestPath = path.join(androidDir, 'app', 'src', 'main', 'AndroidManifest.xml');
453
607
  if (fs.existsSync(manifestPath)) {
454
608
  try {
@@ -469,18 +623,124 @@ if (fs.existsSync(androidDir)) {
469
623
  }
470
624
  if (changed) {
471
625
  fs.writeFileSync(manifestPath, manifest, 'utf8');
472
- console.log('✅ Đã thêm permissions vào AndroidManifest.xml');
626
+ console.log('✅ Added permissions to AndroidManifest.xml');
473
627
  } else {
474
- console.log('ℹ️ Permissions Android đã đầy đủ');
628
+ console.log('ℹ️ Android permissions are already up-to-date');
475
629
  }
476
630
  } catch (e) {
477
- console.warn('⚠️ Không thể cập nhật AndroidManifest.xml:', e.message);
631
+ console.warn('⚠️ Failed to update AndroidManifest.xml:', e.message);
478
632
  }
479
633
  }
480
634
  }
481
635
 
482
- console.log('\n🎉 THIẾT LẬP HOÀN TẤT 100%!');
483
- console.log('👉 Bạn có thể chạy ứng dụng ngay bây giờ:');
636
+ // 6. Ensure widgets.config.ts exists
637
+ const configCandidates = [
638
+ 'widgets.config.ts',
639
+ 'widgets.config.js',
640
+ 'widgets.config.mjs',
641
+ 'widgets.config.cjs',
642
+ 'widgets.config.json',
643
+ ];
644
+ const hasConfig = configCandidates.some((c) => fs.existsSync(path.join(projectRoot, c)));
645
+ if (!hasConfig) {
646
+ const targetConfig = path.join(projectRoot, 'widgets.config.ts');
647
+ const defaultTemplate = `import { defineWidgetConfig } from 'react-native-live-widgets';
648
+
649
+ /**
650
+ * ==============================================================================
651
+ * react-native-live-widgets Configuration (widgets.config.ts)
652
+ * ==============================================================================
653
+ *
654
+ * This configuration file drives the TypeScript codegen engine.
655
+ * Run the following command whenever you modify this file:
656
+ *
657
+ * npx react-native-live-widgets codegen
658
+ *
659
+ * It will automatically:
660
+ * 1. Generate 'LiveWidgetsBundle.swift' for iOS WidgetKit Extension.
661
+ * 2. Generate modern Apple String Catalog ('Localizable.xcstrings').
662
+ * 3. Synchronize Android string resources ('res/values-{lang}/strings.xml').
663
+ * 4. Synchronize SF Symbols (iOS) & Material Icons (Android) type definitions.
664
+ * ==============================================================================
665
+ */
666
+ export default defineWidgetConfig({
667
+ /**
668
+ * The name of the Swift WidgetBundle struct generated in the iOS extension.
669
+ * Default: 'LiveWidgetsBundle'
670
+ */
671
+ bundleName: 'LiveWidgetsBundle',
672
+
673
+ /**
674
+ * Enable or disable iOS Lock Screen Live Activities & Dynamic Island.
675
+ * Set to 'false' if your application only uses Home Screen widgets.
676
+ */
677
+ liveActivity: true,
678
+
679
+ /**
680
+ * Enable or disable iOS 18+ Interactive Control Center widgets.
681
+ */
682
+ controlWidgets: true,
683
+
684
+ /**
685
+ * Default fallback locale for widget titles, descriptions, and static labels.
686
+ */
687
+ defaultLocale: 'vi',
688
+
689
+ /**
690
+ * Multi-language translation catalog.
691
+ * Keys defined here are automatically mapped to:
692
+ * - iOS: Localizable.xcstrings (LocalizedStringKey in Swift)
693
+ * - Android: res/values-{lang}/strings.xml (R.string in Kotlin/Java)
694
+ */
695
+ locales: {
696
+ vi: {
697
+ 'widgets.main.title': 'Tiện ích Live Widgets',
698
+ 'widgets.main.desc': 'Tự động đồng bộ và hiển thị theo mẫu giao diện bạn chọn trong ứng dụng.',
699
+ },
700
+ en: {
701
+ 'widgets.main.title': 'Live Widgets Utility',
702
+ 'widgets.main.desc': 'Automatically syncs and displays layouts defined in your React Native app.',
703
+ },
704
+ },
705
+
706
+ /**
707
+ * List of registered Home Screen widgets.
708
+ * Each entry maps to a distinct timeline provider and widget kind.
709
+ */
710
+ widgets: [
711
+ {
712
+ /** Unique key identifier used in Widget.setLayout('<key>', ...) */
713
+ key: 'main',
714
+
715
+ /** Native Swift struct kind name generated in WidgetBundle */
716
+ kind: 'DynamicHomeScreenWidget',
717
+
718
+ /** Display name shown in the iOS & Android Widget Gallery picker */
719
+ displayName: 'widgets.main.title',
720
+
721
+ /** Description shown below the widget preview in the Widget Gallery */
722
+ description: 'widgets.main.desc',
723
+
724
+ /** Supported widget sizes for this widget */
725
+ supportedFamilies: ['systemSmall', 'systemMedium', 'systemLarge'],
726
+ },
727
+ ],
728
+ });
729
+ `;
730
+ fs.writeFileSync(targetConfig, defaultTemplate, 'utf8');
731
+ console.log('✅ Created default configuration: widgets.config.ts');
732
+ }
733
+
734
+ // 7. Automatically run Codegen to generate icons, localizations, and LiveWidgetsBundle.swift
735
+ try {
736
+ const { runCodegen } = require('./codegen');
737
+ runCodegen(projectRoot);
738
+ } catch (codegenErr) {
739
+ console.warn('⚠️ Codegen warning:', codegenErr.message);
740
+ }
741
+
742
+ console.log('🎉 SETUP 100% COMPLETE!');
743
+ console.log('👉 You can now run your application:');
484
744
  if (isExpo) {
485
745
  console.log(' - iOS: npx expo run:ios');
486
746
  console.log(' - Android: npx expo run:android');
@@ -1,6 +1,6 @@
1
1
  # EXPO INTEGRATION & USAGE GUIDE FOR REACT-NATIVE-LIVE-WIDGETS 🚀
2
2
 
3
- > 🌐 **Language:** **English** • [🇻🇳 Hướng dẫn Tiếng Việt (EXPO-GUIDE-VI.md)](./EXPO-GUIDE-VI.md) • [📖 Bare RN Guide (GUIDE-EN.md)](./GUIDE-EN.md) • [⚡ Expo Live Demo Repository](https://github.com/React-Native-Vu/LiveWidgetsExampleExpo)
3
+ > 🌐 **Language:** **English** • [🇻🇳 Hướng dẫn Tiếng Việt (EXPO-GUIDE-VI.md)](./EXPO-GUIDE-VI.md) • [📖 Bare RN Guide (GUIDE-EN.md)](./GUIDE-EN.md) • [⚡ Expo Live Demo Repository](https://github.com/React-Native-Vu/LiveWidgetsExampleExpo) • [🌐 Web Docs (Live Simulator)](https://react-native-vu.github.io/react-native-live-widgets/)
4
4
 
5
5
  This guide provides a comprehensive walkthrough for integrating **`react-native-live-widgets`** into **Expo (SDK 50, 51, 52, 58+)** projects — covering Expo Config Plugins, automatic iOS WidgetKit/ActivityKit configuration, local testing via Expo Dev Client, and production cloud builds with **EAS Build**.
6
6
 
@@ -86,7 +86,25 @@ npx expo run:android
86
86
 
87
87
  ## 3. Step-by-Step Installation & Setup
88
88
 
89
- ### Step 1: Install Package
89
+ ### Fastest Method: 100% Automated 1-Command Setup
90
+
91
+ ```bash
92
+ # 1. Install package
93
+ npx expo install react-native-live-widgets
94
+
95
+ # 2. Automated one-command setup (auto-injects Config Plugin, creates widgets.config.ts, syncs icons & Swift)
96
+ npx react-native-live-widgets init
97
+
98
+ # 3. Launch on Simulator / Emulator
99
+ npx expo run:ios
100
+ # or: npx expo run:android
101
+ ```
102
+
103
+ ---
104
+
105
+ ### Manual Workflow (If you prefer configuring by hand)
106
+
107
+ #### Step 1: Install Package
90
108
  In your Expo project root:
91
109
  ```bash
92
110
  npx expo install react-native-live-widgets
@@ -94,7 +112,7 @@ npx expo install react-native-live-widgets
94
112
 
95
113
  ---
96
114
 
97
- ### Step 2: Configure `app.json` (Expo Config Plugin)
115
+ #### Step 2: Configure `app.json` (Expo Config Plugin)
98
116
  Open `app.json` and add the `react-native-live-widgets` plugin under `expo.plugins`:
99
117
 
100
118
  ```json