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.
- package/CHANGELOG.md +21 -0
- package/README.md +113 -10
- package/android/src/main/java/com/reactnativeliveactivity/bridge/LiveActivityModule.kt +5 -1
- package/android/src/main/java/com/reactnativeliveactivity/renderer/DynamicWidgetCanvasRenderer.kt +443 -46
- package/android/src/main/java/com/reactnativeliveactivity/storage/DynamicWidgetStateStore.kt +86 -24
- package/android/src/main/java/com/reactnativeliveactivity/widgets/DynamicHomeScreenWidgetProvider.kt +126 -56
- package/android/src/main/res/layout/rn_live_widget_hit_zone.xml +16 -0
- package/android/src/main/res/layout/rn_live_widget_host.xml +16 -87
- package/docs/GUIDE-EN.md +332 -7
- package/docs/GUIDE-VI.md +357 -7
- package/docs/index.html +1143 -227
- package/docs/llms-full.txt +46 -6
- package/docs/llms.txt +37 -7
- package/ios/Models/DynamicLayoutModels.swift +11 -1
- package/ios/Renderer/DynamicNodeView.swift +169 -14
- package/ios/Widgets/DynamicHomeScreenWidget.swift +7 -3
- package/lib/builder.d.ts.map +1 -1
- package/lib/builder.js +92 -28
- package/lib/builder.js.map +1 -1
- package/lib/dispatcher.d.ts +7 -0
- package/lib/dispatcher.d.ts.map +1 -1
- package/lib/dispatcher.js +23 -6
- package/lib/dispatcher.js.map +1 -1
- package/lib/hooks.d.ts +66 -0
- package/lib/hooks.d.ts.map +1 -0
- package/lib/hooks.js +171 -0
- package/lib/hooks.js.map +1 -0
- package/lib/index.d.ts +48 -8
- package/lib/index.d.ts.map +1 -1
- package/lib/index.js +216 -35
- package/lib/index.js.map +1 -1
- package/lib/ir.d.ts +15 -0
- package/lib/ir.d.ts.map +1 -0
- package/lib/ir.js +379 -0
- package/lib/ir.js.map +1 -0
- package/lib/jsx.d.ts +87 -0
- package/lib/jsx.d.ts.map +1 -0
- package/lib/jsx.js +243 -0
- package/lib/jsx.js.map +1 -0
- package/lib/preview.d.ts +31 -0
- package/lib/preview.d.ts.map +1 -0
- package/lib/preview.js +735 -0
- package/lib/preview.js.map +1 -0
- package/lib/types.d.ts +212 -12
- package/lib/types.d.ts.map +1 -1
- package/lib/types.js +2 -1
- package/lib/types.js.map +1 -1
- package/package.json +3 -1
- package/src/builder.ts +86 -21
- package/src/dispatcher.ts +17 -0
- package/src/hooks.ts +223 -0
- package/src/index.ts +202 -13
- package/src/ir.ts +430 -0
- package/src/jsx.tsx +326 -0
- package/src/preview.tsx +1043 -0
- package/src/react-ambient.d.ts +10 -0
- package/src/react-native-env.d.ts +44 -0
- 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
|
-
- π¨ **
|
|
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. β‘
|
|
117
|
-
-
|
|
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
|
-
|
|
121
|
-
|
|
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
|
|
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
|
-
###
|
|
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
|
-
###
|
|
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',
|
|
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',
|
|
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.
|
|
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
|
}
|