react-native-live-widgets 1.1.1 β†’ 1.2.1

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 (58) hide show
  1. package/CHANGELOG.md +21 -0
  2. package/README.md +113 -10
  3. package/android/src/main/java/com/reactnativeliveactivity/bridge/LiveActivityModule.kt +5 -1
  4. package/android/src/main/java/com/reactnativeliveactivity/renderer/DynamicWidgetCanvasRenderer.kt +443 -46
  5. package/android/src/main/java/com/reactnativeliveactivity/storage/DynamicWidgetStateStore.kt +86 -24
  6. package/android/src/main/java/com/reactnativeliveactivity/widgets/DynamicHomeScreenWidgetProvider.kt +126 -56
  7. package/android/src/main/res/layout/rn_live_widget_hit_zone.xml +16 -0
  8. package/android/src/main/res/layout/rn_live_widget_host.xml +16 -87
  9. package/docs/GUIDE-EN.md +332 -7
  10. package/docs/GUIDE-VI.md +357 -7
  11. package/docs/index.html +1143 -227
  12. package/docs/llms-full.txt +46 -6
  13. package/docs/llms.txt +37 -7
  14. package/ios/Models/DynamicLayoutModels.swift +11 -1
  15. package/ios/Renderer/DynamicNodeView.swift +169 -14
  16. package/ios/Widgets/DynamicHomeScreenWidget.swift +7 -3
  17. package/lib/builder.d.ts.map +1 -1
  18. package/lib/builder.js +92 -28
  19. package/lib/builder.js.map +1 -1
  20. package/lib/dispatcher.d.ts +7 -0
  21. package/lib/dispatcher.d.ts.map +1 -1
  22. package/lib/dispatcher.js +23 -6
  23. package/lib/dispatcher.js.map +1 -1
  24. package/lib/hooks.d.ts +66 -0
  25. package/lib/hooks.d.ts.map +1 -0
  26. package/lib/hooks.js +171 -0
  27. package/lib/hooks.js.map +1 -0
  28. package/lib/index.d.ts +48 -8
  29. package/lib/index.d.ts.map +1 -1
  30. package/lib/index.js +216 -35
  31. package/lib/index.js.map +1 -1
  32. package/lib/ir.d.ts +15 -0
  33. package/lib/ir.d.ts.map +1 -0
  34. package/lib/ir.js +379 -0
  35. package/lib/ir.js.map +1 -0
  36. package/lib/jsx.d.ts +87 -0
  37. package/lib/jsx.d.ts.map +1 -0
  38. package/lib/jsx.js +243 -0
  39. package/lib/jsx.js.map +1 -0
  40. package/lib/preview.d.ts +31 -0
  41. package/lib/preview.d.ts.map +1 -0
  42. package/lib/preview.js +735 -0
  43. package/lib/preview.js.map +1 -0
  44. package/lib/types.d.ts +212 -12
  45. package/lib/types.d.ts.map +1 -1
  46. package/lib/types.js +2 -1
  47. package/lib/types.js.map +1 -1
  48. package/package.json +3 -1
  49. package/src/builder.ts +86 -21
  50. package/src/dispatcher.ts +17 -0
  51. package/src/hooks.ts +223 -0
  52. package/src/index.ts +202 -13
  53. package/src/ir.ts +430 -0
  54. package/src/jsx.tsx +326 -0
  55. package/src/preview.tsx +1043 -0
  56. package/src/react-ambient.d.ts +10 -0
  57. package/src/react-native-env.d.ts +44 -0
  58. package/src/types.ts +261 -13
package/CHANGELOG.md CHANGED
@@ -2,6 +2,27 @@
2
2
 
3
3
  All notable changes to `react-native-live-widgets` will be documented in this file.
4
4
 
5
+ ## [1.2.1] - 2026-11-17
6
+ ### Fixed
7
+ - **iOS Swift 6 Compatibility**: Resolved `@ViewBuilder` type inference and closure encapsulation for `renderText()`, `DynamicNodeAccessibilityModifier`, and `ContainerStyleModifier` to prevent `type '()' cannot conform to 'View'` compiler error.
8
+ - **Android Exact Hit Layer**: Replaced fixed grid layout with dynamic `FrameLayout` hit zones (`rn_hit_layer`), accurately mapping bitmap coordinates with launcher aspect ratio letterboxing to eliminate touch offsets and misclicks.
9
+ - **Android Live Chronometer**: Integrated native `android.widget.Chronometer` with `setChronometerCountDown(true)` for smooth, real-time 1s countdown ticking without redrawing bitmaps.
10
+ - **Dynamic Variable Interpolation**: Added dynamic template variable resolution (`{{id}}`, `{{title}}`, counter values) and `defaultChecked` persistence in `DynamicWidgetStateStore`.
11
+
12
+ ## [1.2.0] - 2026-11-16
13
+ ### Added
14
+ - **JSX / TSX Declarative DSL**: Support building Widgets and Live Activities directly using intuitive React JSX syntax (`<VStack>`, `<HStack>`, `<ZStack>`, `<Grid>`, `<Text>`, `<Button>`, `<Badge>`, `<Progress>`, `<Timer>`, `<Image>`, `<Spacer>`, `<Divider>`) instead of nested function calls `UI.VStack(...)`.
15
+ - **In-App Widget Preview (`<WidgetPreview>` / `<VoltraWidgetPreview>`)**: Live component to render, preview, and test widget layouts and interactive button clicks directly inside your React Native screens with accurate device sizes (`small`, `medium`, `large`, `lockScreen`).
16
+ - **Seamless JSX Auto-Conversion**: `Widget.setLayout(...)` and `LiveActivity.start(...)` now accept JSX elements directly and convert them automatically into native `LayoutNode` JSON trees.
17
+
18
+ ## [1.1.2] - 2026-11-16
19
+ ### Added
20
+ - **React Hooks (Fast Refresh Resilient)**: Added `useWidgetAction`, `useLiveActivity`, and `useWidgetState` hooks with automatic lifecycle cleanup and Hot Reload resilience.
21
+ - **API Overload & Aliases**: Added `Widget.onWidgetAction`, `LiveActivity.registerActionHandler`, `Widget.update`, `cornerRadius` alias for `borderRadius`, and normalized `intervalMinutes` <-> `refreshIntervalMinutes` across TypeScript, Android (Kotlin), and iOS (Swift).
22
+
23
+ ### Documentation
24
+ - **Complete Documentation Synchronization**: Standardized function signatures, props, and code snippets across `README.md`, `GUIDE-VI.md`, `GUIDE-EN.md`, `docs/index.html`, `llms.txt`, and Agent Skill.
25
+
5
26
  ## [1.1.1] - 2026-11-16
6
27
  ### Fixed
7
28
  - **Android Widget Interaction Crash**: Added `android.permission.WAKE_LOCK` and safely wrapped `HeadlessJsTaskService` wake lock acquisition to prevent `SecurityException` on widget tap events.
package/README.md CHANGED
@@ -91,7 +91,8 @@ Until now, adding **Live Activities** or **Home Screen Widgets** to a React Nati
91
91
 
92
92
  `react-native-live-widgets` solves this with a **Declarative TypeScript UI DSL**:
93
93
  - 🚫 **No SwiftUI / Kotlin coding required** for custom screens.
94
- - 🎨 **100% Declarative UI in React Native (`UI.VStack`, `UI.HStack`, `UI.Text`, `UI.Button`, `UI.Progress`, `UI.Image`)**.
94
+ - 🎨 **Dual UI Syntax**: Choose between **React JSX/TSX (`<VStack>`, `<Text>`, `<Button>`)** or **Functional DSL (`UI.VStack(...)`)**.
95
+ - πŸ“± **In-App Widget Preview (`<WidgetPreview>`)**: Preview and test widget interactions directly on your app screen.
95
96
  - πŸš€ **Full Expo & EAS Build Support** via automated Expo Config Plugin (`app.plugin.js`).
96
97
  - ⚑ **Interactive Buttons**: Tap buttons on the Home Screen Widget to run native Swift extensions or wake up TypeScript handlers.
97
98
  - πŸ”„ **Realtime Data Sync (`SharedStorage`)**: Single source of truth across Main App, Lock Screen, and Home Screen.
@@ -113,17 +114,32 @@ Until now, adding **Live Activities** or **Home Screen Widgets** to a React Nati
113
114
  - **Checklist & Toggles**: Toggle checkboxes and switch states without opening the app (`actionId: "toggle:<key>"`).
114
115
  - **Dark & Light Mode**: Declarative color tokens `{ light: '#FFF', dark: '#0F172A' }`.
115
116
 
116
- ### 3. ⚑ Bi-directional Action Dispatcher (TypeScript + Native)
117
- - Tap a widget button outside on the Home Screen to trigger a registered TypeScript function:
117
+ ### 3. ⚑ React Hooks & Fast Refresh Resilient
118
+ - **`useWidgetAction(actionId, callback)`**: Automatically registers and cleans up widget button tap listeners on unmount. 100% resilient to React Native Fast Refresh / Hot Reloading!
119
+ ```tsx
120
+ useWidgetAction('action_checkin', async (payload) => {
121
+ console.log('Action triggered from Home Screen Widget:', payload);
122
+ });
123
+ ```
124
+ - **`useLiveActivity()`**: Track activity state, push tokens, and control start / update / end directly in React components.
125
+ - **`useWidgetState(key, initialValue)`**: Synchronize local component state with Widget Shared Storage and trigger instant OS re-renders.
126
+
127
+ ### 4. ⚑ Bi-directional Action Dispatcher (TypeScript + Native)
128
+ - Imperative action registration for background services:
118
129
  ```ts
119
130
  LiveActivity.registerAction('action_checkin', async (payload) => {
120
- // Runs inside React Native JS engine!
121
- console.log('Action triggered from Home Screen Widget:', payload);
131
+ console.log('Action triggered:', payload);
132
+ });
133
+ // Or listen globally to all widget actions:
134
+ Widget.onWidgetAction((actionId, payload) => {
135
+ console.log(`Action ${actionId} received`, payload);
122
136
  });
123
137
  ```
124
- - **App-Killed Protection**: Native fallback ensures UI responds instantly and persists data even if the main app is terminated.
138
+ - **App-Killed Background Support**:
139
+ - **Android**: Supports `LiveActivity.registerBackgroundActionHandler()` via Headless JS tasks and instant native state persistence in `DynamicWidgetStateStore`.
140
+ - **iOS**: Apple sandboxes widget extensions when the main app is force-killed. Button taps update native App Group state directly; JavaScript callbacks resume automatically when the app is reopened.
125
141
 
126
- ### 4. 🌐 Background Remote API Sync (Zero Code Backend)
142
+ ### 5. 🌐 Background Remote API Sync (Zero Code Backend)
127
143
  - Configure an API endpoint with `Widget.setRemoteConfig`:
128
144
  ```ts
129
145
  await Widget.setRemoteConfig('main', {
@@ -134,7 +150,7 @@ Until now, adding **Live Activities** or **Home Screen Widgets** to a React Nati
134
150
  ```
135
151
  - The native Extension fetches fresh JSON and dynamically replaces `{{variables}}` in your widget layout in the background.
136
152
 
137
- ### 5. πŸ”” APNs & FCM Token Management
153
+ ### 6. πŸ”” APNs & FCM Token Management
138
154
  - One-call retrieval for all push tokens:
139
155
  ```ts
140
156
  const tokens = await LiveActivity.getAllPushTokens();
@@ -143,6 +159,45 @@ Until now, adding **Live Activities** or **Home Screen Widgets** to a React Nati
143
159
  // tokens.activityUpdateToken
144
160
  ```
145
161
 
162
+ ### 7. 🎨 Advanced Styling Modifiers & Platform Capability Matrix
163
+
164
+ Build deep, rich widgets with design system foundations across both platforms:
165
+
166
+ - **🌈 Gradients**: Linear and radial gradients on Containers, Cards, and Buttons:
167
+ ```tsx
168
+ <VStack gradient={{ colors: ['#1E3A8A', '#3B82F6'], angle: 90 }} padding={14}>
169
+ ```
170
+ - **πŸ”² Borders & Dashed Lines**: Full control over width, color, and stroke styles (`'solid' | 'dashed' | 'dotted'`).
171
+ - **πŸŒ‘ Shadows & Depth**: Elevate cards with `shadowColor`, `shadowRadius`, `shadowOpacity`, and `shadowOffset`.
172
+ - **πŸ”€ Typography & Dynamic Type**: Semantic scale (`largeTitle`, `title`, `headline`, `subheadline`, `body`, `caption`, `footnote`) with auto-scaling for OS Accessibility font sizes.
173
+ - **πŸŒ— Light, Dark & Tinted Mode**: Support for iOS 18 Tinted Home Screen icons and Android Material You dynamic coloring via `{ light: '#FFF', dark: '#0F172A', tinted: '#38BDF8' }`.
174
+ - **🌍 RTL Internationalization**: Automatic reverse row alignment (`direction: 'rtl'` or `isRTL: true`) for Arabic, Hebrew, and other RTL locales.
175
+ - **β™Ώ Accessibility & Semantics**: First-class TalkBack & VoiceOver support via `accessible`, `accessibilityLabel`, `accessibilityHint`, `accessibilityRole`, and `accessibilityValue`. Android Canvas generates an aggregated semantic summary on the canvas and individual `contentDescription` on interactive hit-zones.
176
+
177
+ #### πŸ“Š Platform Capability & Fallback Matrix
178
+
179
+ Rather than making unverified claims of "100% parity", the engine provides an explicit, transparent capability matrix paired with automatic **Graceful Fallbacks**:
180
+
181
+ | Feature / Modifier | iOS WidgetKit | iOS Live Activity | Android Ongoing Notification | Android Home Widget | Graceful Fallback Mechanism |
182
+ | :--- | :---: | :---: | :---: | :---: | :--- |
183
+ | **Declarative Layouts (`VStack`/`HStack`/`Grid`)** | βœ… Native | βœ… Native | βœ… Canvas | βœ… 2D Canvas | 100% pixel-aligned across all platforms |
184
+ | **Accessibility (TalkBack / VoiceOver)** | βœ… Native VoiceOver | βœ… Native VoiceOver | βœ… Notification Text | βœ… A11y Summary + Hit-Zones | Aggregated `contentDescription` ensures full screen-reader readability |
185
+ | **Linear / Radial Gradients** | βœ… SwiftUI | βœ… SwiftUI | βœ… Shader | βœ… Shader | Automatically falls back to dominant solid `backgroundColor` |
186
+ | **Card & Text Shadows** | βœ… SwiftUI | βœ… SwiftUI | ⚠️ Text Only | βœ… `setShadowLayer` | Falls back to elevation or thin border stroke |
187
+ | **Dashed / Dotted Borders** | βœ… StrokeStyle | βœ… StrokeStyle | ⚠️ Solid | βœ… `DashPathEffect` | Automatically falls back to solid border |
188
+ | **Dynamic Type (Accessibility)** | βœ… Native | βœ… Native | βœ… `fontScale` | βœ… `fontScale` | Preserves accessibility scale factor across devices |
189
+ | **RTL Layout Mirroring** | βœ… Native | βœ… Native | βœ… RTL | βœ… RTL | Reverses flex order and flips text alignment |
190
+ | **iOS 18 Tinted Mode** | βœ… Accentable | N/A | N/A | βœ… Material You | Resolves `tinted` key on iOS 18; falls back to dark/light color |
191
+ | **Interactive Background Intents** | βœ… iOS 17+ | βœ… iOS 17+ | βœ… Native Intent | βœ… Native Intent | Updates local Shared Storage and refreshes timeline |
192
+
193
+ #### πŸ” Checking Runtime Capabilities Programmatically
194
+ ```ts
195
+ const caps = await Widget.getCapabilities();
196
+ if (caps.supportsGradients) {
197
+ console.log('Device supports native gradients!');
198
+ }
199
+ ```
200
+
146
201
  ---
147
202
 
148
203
  ## ⚑ Quick Start
@@ -251,7 +306,7 @@ await LiveActivity.start({
251
306
  )
252
307
  },
253
308
  lockScreen: UI.VStack(
254
- { padding: 16, backgroundColor: '#0F172A', cornerRadius: 16 },
309
+ { padding: 16, backgroundColor: '#0F172A', borderRadius: 16 },
255
310
  UI.HStack(
256
311
  { justifyContent: 'spaceBetween' },
257
312
  UI.Text('KPI QuΓ½ 4: Đẑt 86% mα»₯c tiΓͺu', { fontSize: 14, fontWeight: 'bold', color: '#FFFFFF' }),
@@ -282,7 +337,7 @@ await SharedStorage.set('revenue_month', '4.85 Tα»· Δ‘', APP_GROUP);
282
337
  // Build Declarative Layout
283
338
  await Widget.setLayout('main', {
284
339
  large: UI.VStack(
285
- { padding: 16, backgroundColor: '#0B132B', cornerRadius: 20 },
340
+ { padding: 16, backgroundColor: '#0B132B', borderRadius: 20 },
286
341
  UI.HStack(
287
342
  { justifyContent: 'spaceBetween' },
288
343
  UI.Text('Tα»”NG QUAN ĐIỀU HΓ€NH (KPI & BIα»‚U ĐỒ)', { fontSize: 11, color: '#38BDF8', fontWeight: 'bold' }),
@@ -309,6 +364,54 @@ await Widget.setLayout('main', {
309
364
  await Widget.reloadAll();
310
365
  ```
311
366
 
367
+ ### 3. Build Widgets with React JSX / TSX Syntax
368
+
369
+ Prefer JSX over nested functions? Build layouts using clean, declarative JSX with full `style` prop & array flattening support:
370
+
371
+ ```tsx
372
+ import { Widget, VStack, HStack, Text, Badge, Progress, Button } from 'react-native-live-widgets';
373
+
374
+ await Widget.setLayout('main', {
375
+ medium: (
376
+ <VStack padding={16} backgroundColor="#0F172A" borderRadius={16}>
377
+ <HStack justifyContent="spaceBetween">
378
+ <Text fontSize={14} fontWeight="bold" color="#FFFFFF">VΓ o ca sΓ‘ng</Text>
379
+ <Badge text="07:54 (Hợp lệ)" backgroundColor="#064E3B" textColor="#6EE7B7" />
380
+ </HStack>
381
+ <Progress value={0.75} style="segmented" segments={4} tintColor="#38BDF8" height={8} />
382
+ <Button title="LΓ m mα»›i dα»― liệu" actionId="refresh" fullWidth />
383
+ </VStack>
384
+ )
385
+ });
386
+ ```
387
+
388
+ ### 4. In-App Live Widget Preview (`<WidgetPreview>` / `<VoltraWidgetPreview>`)
389
+
390
+ Test and preview widgets directly inside your app screens with pixel-accurate OS container frames and real-time button clicks:
391
+
392
+ ```tsx
393
+ import { WidgetPreview, VStack, HStack, Text, Button } from 'react-native-live-widgets';
394
+
395
+ export function WidgetDemoScreen() {
396
+ return (
397
+ <WidgetPreview
398
+ size="medium" // 'small' | 'medium' | 'large' | 'lockScreen'
399
+ showBadge={true}
400
+ interactiveSizeSwitch={true} // Quick tabs to test small / medium / large
401
+ onAction={(actionId) => console.log('Tapped action:', actionId)}
402
+ >
403
+ <VStack padding={16} backgroundColor="#0F172A" borderRadius={20}>
404
+ <HStack justifyContent="spaceBetween">
405
+ <Text fontSize={14} fontWeight="bold" color="#FFFFFF">KPI TuαΊ§n</Text>
406
+ <Text fontSize={12} color="#38BDF8">86%</Text>
407
+ </HStack>
408
+ <Button title="Check-in ngay" actionId="checkin" fullWidth />
409
+ </VStack>
410
+ </WidgetPreview>
411
+ );
412
+ }
413
+ ```
414
+
312
415
  ---
313
416
 
314
417
  ## πŸ“Š Platform Feature Parity Matrix
@@ -289,7 +289,11 @@ class LiveActivityModule(private val reactContext: ReactApplicationContext) :
289
289
  val wKey = key.removePrefix("widget_remote_config_")
290
290
  runCatching {
291
291
  val cfg = JSONObject(value)
292
- val mins = cfg.optInt("refreshIntervalMinutes", 15).coerceAtLeast(1)
292
+ val mins = if (cfg.has("refreshIntervalMinutes")) {
293
+ cfg.optInt("refreshIntervalMinutes", 15)
294
+ } else {
295
+ cfg.optInt("intervalMinutes", 15)
296
+ }.coerceAtLeast(1)
293
297
  DynamicWidgetStateStore.scheduleBackgroundWidgetSync(reactContext, wKey, mins)
294
298
  }
295
299
  }