react-native-demo-library-by-rinkal 1.2.7 → 1.3.0

package/COMMUNICATION_DOCS.md

@@ -0,0 +1,336 @@
+# MiniApp-Container Communication Patterns
+
+## Overview
+This library implements 6 different communication patterns between miniapps and container apps in React Native.
+
+## Official Documentation References
+
+### 1. **Event Emitter Pattern**
+- **Reference**: [React Native Events](https://reactnative.dev/docs/native-modules-ios#sending-events-to-javascript)
+- **Documentation**: https://reactnative.dev/docs/native-modules-ios#sending-events-to-javascript
+- **Node.js EventEmitter**: https://nodejs.org/api/events.html
+
+### 2. **Callback Pattern**
+- **Reference**: [React Native Callbacks](https://reactnative.dev/docs/native-modules-ios#callbacks)
+- **Documentation**: https://reactnative.dev/docs/native-modules-ios#callbacks
+
+### 3. **Promise-Based Pattern**
+- **Reference**: [React Native Promises](https://reactnative.dev/docs/native-modules-ios#promises)
+- **Documentation**: https://reactnative.dev/docs/native-modules-ios#promises
+- **JavaScript Promises**: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise
+
+### 4. **Shared State Pattern**
+- **Reference**: [Redux State Management](https://redux.js.org/introduction/getting-started)
+- **Documentation**: https://redux.js.org/introduction/getting-started
+- **React Context**: https://react.dev/reference/react/useContext
+
+### 5. **Native Bridge Pattern**
+- **Reference**: [React Native Native Modules](https://reactnative.dev/docs/native-modules-intro)
+- **iOS Documentation**: https://reactnative.dev/docs/native-modules-ios
+- **Android Documentation**: https://reactnative.dev/docs/native-modules-android
+- **Communication iOS**: https://reactnative.dev/docs/communication-ios
+- **Communication Android**: https://reactnative.dev/docs/communication-android
+
+### 6. **Message Queue Pattern**
+- **Reference**: [Message Queue Pattern](https://en.wikipedia.org/wiki/Message_queue)
+- **Documentation**: https://en.wikipedia.org/wiki/Message_queue
+
+### Additional Web-Based References
+- **Window postMessage API**: https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage
+- **Custom Events**: https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent
+- **Web Workers**: https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API
+
+---
+
+## Communication Patterns
+
+### 1. Event Emitter Pattern
+**Use Case**: One-way communication, fire-and-forget events
+
+```typescript
+// MiniApp Side
+import MiniAppCommunication from 'react-native-demo-library-by-rinkal';
+
+// Send event
+MiniAppCommunication.sendEvent('userAction', { action: 'buttonClicked' });
+
+// Listen to events
+const subscription = MiniAppCommunication.onEvent('containerUpdate', (data) => {
+  console.log('Received:', data);
+});
+
+// Container Side
+import ContainerCommunication from 'react-native-demo-library-by-rinkal';
+
+// Listen to events from miniapp
+ContainerCommunication.onEvent('userAction', (data) => {
+  console.log('User action:', data);
+});
+
+// Send event to miniapp
+ContainerCommunication.sendEvent('containerUpdate', { message: 'Hello' });
+```
+
+### 2. Callback Pattern
+**Use Case**: Direct function invocation, synchronous communication
+
+```typescript
+// MiniApp Side
+MiniAppCommunication.registerCallback('onDataReceived', (data) => {
+  console.log('Callback invoked:', data);
+});
+
+// Container invokes the callback
+MiniAppCallback.invokeCallback('onDataReceived', { result: 'success' });
+```
+
+### 3. Promise-Based Pattern
+**Use Case**: Async request-response, waiting for results
+
+```typescript
+// MiniApp Side
+const result = await MiniAppCommunication.request('getUserData', {
+  userId: '123'
+});
+console.log('Result:', result);
+
+// Container Side
+ContainerCommunication.registerHandler('getUserData', async (data) => {
+  // Fetch user data
+  return {
+    userId: data.userId,
+    name: 'John Doe',
+    email: 'john@example.com'
+  };
+});
+```
+
+### 4. Shared State Pattern
+**Use Case**: Bidirectional state synchronization
+
+```typescript
+// MiniApp Side
+// Set state
+MiniAppCommunication.setState('userData', { name: 'John' });
+
+// Get state
+const userData = MiniAppCommunication.getState('userData');
+
+// Subscribe to changes
+const unsubscribe = MiniAppCommunication.subscribeToState('userData', (newValue) => {
+  console.log('State changed:', newValue);
+});
+
+// Container Side
+// Set state
+ContainerCommunication.setState('userData', { name: 'Jane' });
+
+// Subscribe to changes
+ContainerCommunication.subscribeToState('userData', (newValue) => {
+  console.log('State changed:', newValue);
+});
+```
+
+### 5. Native Bridge Pattern
+**Use Case**: Direct native module communication
+
+```typescript
+// MiniApp Side
+const result = await MiniAppCommunication.callNative(
+  'CustomModule',
+  'getDeviceInfo',
+  { param1: 'value' }
+);
+```
+
+**Note**: You need to create native modules first. See:
+- [iOS Native Modules](https://reactnative.dev/docs/native-modules-ios)
+- [Android Native Modules](https://reactnative.dev/docs/native-modules-android)
+
+### 6. Message Queue Pattern
+**Use Case**: Reliable message delivery, offline support
+
+```typescript
+// MiniApp Side
+MiniAppCommunication.queueMessage('analyticsEvent', {
+  event: 'page_view',
+  page: 'home'
+});
+
+// Container Side
+ContainerCommunication.registerMessageHandler('analyticsEvent', (message) => {
+  console.log('Analytics:', message.payload);
+});
+```
+
+---
+
+## Installation & Setup
+
+### 1. Install the package
+```bash
+npm install react-native-demo-library-by-rinkal
+```
+
+### 2. Initialize in your app
+
+**In MiniApp:**
+```typescript
+import MiniAppCommunication from 'react-native-demo-library-by-rinkal';
+
+// Initialize once at app startup
+MiniAppCommunication.initialize();
+```
+
+**In Container:**
+```typescript
+import ContainerCommunication from 'react-native-demo-library-by-rinkal';
+
+// Initialize once at app startup
+ContainerCommunication.initialize();
+```
+
+### 3. Cleanup on unmount
+```typescript
+useEffect(() => {
+  return () => {
+    MiniAppCommunication.cleanup();
+    // or
+    ContainerCommunication.cleanup();
+  };
+}, []);
+```
+
+---
+
+## Complete Examples
+
+### MiniApp Component
+```typescript
+import React, { useEffect } from 'react';
+import { View, Button } from 'react-native';
+import { MiniAppExample } from 'react-native-demo-library-by-rinkal';
+
+const App = () => {
+  return <MiniAppExample />;
+};
+
+export default App;
+```
+
+### Container Component
+```typescript
+import React from 'react';
+import { ContainerExample } from 'react-native-demo-library-by-rinkal';
+
+const App = () => {
+  return <ContainerExample />;
+};
+
+export default App;
+```
+
+---
+
+## Communication Pattern Comparison
+
+| Pattern | Direction | Async | Reliability | Use Case |
+|---------|-----------|-------|-------------|----------|
+| Event Emitter | Bi-directional | No | Medium | Real-time updates |
+| Callback | Uni-directional | No | High | Direct invocation |
+| Promise | Request-Response | Yes | High | Data fetching |
+| Shared State | Bi-directional | No | High | State sync |
+| Native Bridge | Uni-directional | Yes | Medium | Native features |
+| Message Queue | Uni-directional | Yes | Very High | Offline support |
+
+---
+
+## Architecture Diagram
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                      MiniApp                            │
+│  ┌──────────────────────────────────────────────────┐  │
+│  │  MiniAppCommunication                            │  │
+│  │  - Event Emitter                                 │  │
+│  │  - Callbacks                                     │  │
+│  │  - Promises                                      │  │
+│  │  - Shared State                                  │  │
+│  │  - Native Bridge                                 │  │
+│  │  - Message Queue                                 │  │
+│  └──────────────────────────────────────────────────┘  │
+└─────────────────┬───────────────────────────────────────┘
+                  │
+        Event Bus / Bridge / Queue
+                  │
+┌─────────────────┴───────────────────────────────────────┐
+│                  Container App                          │
+│  ┌──────────────────────────────────────────────────┐  │
+│  │  ContainerCommunication                          │  │
+│  │  - Event Listener                                │  │
+│  │  - Request Handlers                              │  │
+│  │  - Shared State Manager                          │  │
+│  │  - Message Queue Handler                         │  │
+│  └──────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Best Practices
+
+1. **Initialize Early**: Call `initialize()` at app startup
+2. **Cleanup Properly**: Always cleanup in `useEffect` cleanup function
+3. **Error Handling**: Wrap async calls in try-catch
+4. **Type Safety**: Use TypeScript for better type safety
+5. **Logging**: Keep console logs for debugging in development
+6. **Performance**: Use message queue for bulk operations
+7. **Security**: Validate all data from untrusted sources
+
+---
+
+## Troubleshooting
+
+### Events not received
+- Ensure both sides are initialized
+- Check event name spelling
+- Verify listeners are registered before events are sent
+
+### Promise timeout
+- Default timeout is 30 seconds
+- Check if container handler is registered
+- Verify network/processing time
+
+### State not syncing
+- Initialize shared state manager
+- Check if subscriptions are active
+- Verify state keys match
+
+---
+
+## Additional Resources
+
+### React Native Documentation
+- [Main Documentation](https://reactnative.dev/docs/getting-started)
+- [Native Modules](https://reactnative.dev/docs/native-modules-intro)
+- [Platform Specific Code](https://reactnative.dev/docs/platform-specific-code)
+
+### Micro-Frontend Patterns
+- [Micro Frontends](https://micro-frontends.org/)
+- [Module Federation](https://webpack.js.org/concepts/module-federation/)
+
+### State Management
+- [Redux](https://redux.js.org/)
+- [MobX](https://mobx.js.org/)
+- [Zustand](https://github.com/pmndrs/zustand)
+
+---
+
+## License
+ISC
+
+## Author
+Rinkal
+
+## Version
+1.2.7

package/CONTAINER_APP_SETUP.md

@@ -0,0 +1,360 @@
+# Container App Setup Guide
+
+## 📱 How to Receive Events from MiniApp in Your Container App (DemoApp)
+
+This guide shows you how to set up your **Container App (DemoApp)** to receive events from the **MiniApp (DemoLib)**.
+
+---
+
+## 🎯 Simple Flow
+
+```
+MiniApp (DemoLib)  ----sends data---->  Container App (DemoApp)
+    TaskCard                                 Your App
+```
+
+---
+
+## 📥 Step 1: Install the Library
+
+In your Container App (DemoApp), install the library:
+
+```bash
+npm install react-native-demo-library-by-rinkal
+```
+
+---
+
+## 📝 Step 2: Create Container Component
+
+In your Container App, create a component to listen for events:
+
+### ContainerApp.tsx (in your DemoApp)
+
+```tsx
+import React, { useEffect, useState } from 'react';
+import { View, Text, StyleSheet, ScrollView } from 'react-native';
+import ContainerCommunication from 'react-native-demo-library-by-rinkal/ContainerCommunication';
+
+const ContainerApp = () => {
+  const [events, setEvents] = useState<string[]>([]);
+
+  useEffect(() => {
+    // Listen to task clicks from miniapp
+    const taskSub = ContainerCommunication.onTaskClick((data) => {
+      console.log('Task clicked in miniapp:', data);
+      setEvents(prev => [...prev, 
+        `📋 Task: ${data.taskTitle} (ID: ${data.taskId})`
+      ]);
+    });
+
+    // Listen to user actions from miniapp
+    const actionSub = ContainerCommunication.onUserAction((data) => {
+      console.log('User action in miniapp:', data);
+      setEvents(prev => [...prev, 
+        `👤 Action: ${data.action}`
+      ]);
+    });
+
+    // Listen to data updates from miniapp
+    const dataSub = ContainerCommunication.onDataUpdate((data) => {
+      console.log('Data update in miniapp:', data);
+      setEvents(prev => [...prev, 
+        `📊 Update: ${data.key} = ${JSON.stringify(data.value)}`
+      ]);
+    });
+
+    // Listen to ANY custom event from miniapp
+    const customSub = ContainerCommunication.listenFromMiniApp('customEvent', (data) => {
+      console.log('Custom event from miniapp:', data);
+      setEvents(prev => [...prev, 
+        `🎯 Custom: ${JSON.stringify(data)}`
+      ]);
+    });
+
+    // Cleanup when component unmounts
+    return () => {
+      taskSub.remove();
+      actionSub.remove();
+      dataSub.remove();
+      customSub.remove();
+    };
+  }, []);
+
+  return (
+    <ScrollView style={styles.container}>
+      <Text style={styles.title}>Container App</Text>
+      <Text style={styles.subtitle}>Listening to MiniApp events...</Text>
+      
+      <View style={styles.eventsBox}>
+        <Text style={styles.eventsTitle}>Received Events:</Text>
+        {events.length === 0 ? (
+          <Text style={styles.emptyText}>
+            Waiting for events from MiniApp...
+          </Text>
+        ) : (
+          events.map((event, index) => (
+            <View key={index} style={styles.eventItem}>
+              <Text style={styles.eventText}>{event}</Text>
+              <Text style={styles.eventTime}>
+                {new Date().toLocaleTimeString()}
+              </Text>
+            </View>
+          ))
+        )}
+      </View>
+    </ScrollView>
+  );
+};
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+    padding: 16,
+    backgroundColor: '#f5f5f5'
+  },
+  title: {
+    fontSize: 24,
+    fontWeight: 'bold',
+    color: '#333',
+    marginBottom: 8
+  },
+  subtitle: {
+    fontSize: 16,
+    color: '#666',
+    marginBottom: 20
+  },
+  eventsBox: {
+    backgroundColor: 'white',
+    padding: 16,
+    borderRadius: 8,
+    shadowColor: '#000',
+    shadowOffset: { width: 0, height: 2 },
+    shadowOpacity: 0.1,
+    shadowRadius: 4,
+    elevation: 3
+  },
+  eventsTitle: {
+    fontSize: 18,
+    fontWeight: '600',
+    marginBottom: 12,
+    color: '#333'
+  },
+  emptyText: {
+    fontSize: 14,
+    color: '#999',
+    fontStyle: 'italic',
+    textAlign: 'center',
+    paddingVertical: 20
+  },
+  eventItem: {
+    padding: 12,
+    backgroundColor: '#f9f9f9',
+    marginBottom: 8,
+    borderRadius: 4,
+    borderLeftWidth: 3,
+    borderLeftColor: '#4CAF50',
+    flexDirection: 'row',
+    justifyContent: 'space-between',
+    alignItems: 'center'
+  },
+  eventText: {
+    fontSize: 14,
+    color: '#333',
+    flex: 1
+  },
+  eventTime: {
+    fontSize: 12,
+    color: '#999',
+    marginLeft: 8
+  }
+});
+
+export default ContainerApp;
+```
+
+---
+
+## 📤 Step 3: Use MiniApp Components
+
+In your Container App, use the MiniApp components:
+
+```tsx
+import React from 'react';
+import { View } from 'react-native';
+import { TaskCard } from 'react-native-demo-library-by-rinkal';
+import ContainerApp from './ContainerApp';
+
+const App = () => {
+  return (
+    <View style={{ flex: 1 }}>
+      {/* Display container listener */}
+      <ContainerApp />
+      
+      {/* MiniApp components - when clicked, sends events to container */}
+      <TaskCard title="Task 1" taskId="task_1" />
+      <TaskCard title="Task 2" taskId="task_2" />
+    </View>
+  );
+};
+
+export default App;
+```
+
+---
+
+## 🎯 Available Listener Methods
+
+### 1. Listen to Task Clicks
+```tsx
+ContainerCommunication.onTaskClick((data) => {
+  // data: { taskId: string, taskTitle: string, timestamp: number }
+  console.log('Task clicked:', data.taskTitle);
+});
+```
+
+### 2. Listen to User Actions
+```tsx
+ContainerCommunication.onUserAction((data) => {
+  // data: { action: string, payload: any, timestamp: number }
+  console.log('User action:', data.action);
+});
+```
+
+### 3. Listen to Data Updates
+```tsx
+ContainerCommunication.onDataUpdate((data) => {
+  // data: { key: string, value: any, timestamp: number }
+  console.log('Data updated:', data.key, data.value);
+});
+```
+
+### 4. Listen to Custom Events
+```tsx
+ContainerCommunication.listenFromMiniApp('customEventName', (data) => {
+  console.log('Custom event received:', data);
+});
+```
+
+---
+
+## 🔧 MiniApp Side (Already Done in DemoLib)
+
+The MiniApp (DemoLib) already has everything set up. The TaskCard component sends events automatically when clicked:
+
+```tsx
+// In DemoLib/TaskCard.tsx (already implemented)
+import MiniAppCommunication from './MiniAppCommunication';
+
+const TaskCard = ({ title, taskId }) => {
+  const handlePress = () => {
+    // This sends event to container automatically
+    MiniAppCommunication.sendTaskClick(taskId, title);
+  };
+  // ... rest of component
+};
+```
+
+You can also send custom events from anywhere in your MiniApp:
+
+```tsx
+// Send custom event from miniapp
+MiniAppCommunication.sendToContainer('customEvent', {
+  type: 'purchase',
+  productId: 'prod_123',
+  amount: 99.99
+});
+
+// Send user action
+MiniAppCommunication.sendUserAction('formSubmit', {
+  formName: 'registration',
+  data: { name: 'John', email: 'john@example.com' }
+});
+
+// Send data update
+MiniAppCommunication.sendDataUpdate('settings', {
+  theme: 'dark',
+  notifications: true
+});
+```
+
+---
+
+## 🔄 Complete Flow Example
+
+### In MiniApp (DemoLib):
+```tsx
+// User taps TaskCard
+<TaskCard title="Buy groceries" taskId="task_123" />
+
+// TaskCard sends event
+MiniAppCommunication.sendTaskClick('task_123', 'Buy groceries');
+```
+
+### In Container (DemoApp):
+```tsx
+// Container receives event
+ContainerCommunication.onTaskClick((data) => {
+  console.log(data);
+  // Output: { taskId: 'task_123', taskTitle: 'Buy groceries', timestamp: 1735462800000 }
+  
+  // Do something with the data
+  navigation.navigate('TaskDetail', { taskId: data.taskId });
+});
+```
+
+---
+
+## 📖 Official Documentation
+
+This implementation uses React Native's DeviceEventEmitter:
+
+- **React Native Native Modules**: https://reactnative.dev/docs/native-modules-intro
+- **Native Modules iOS**: https://reactnative.dev/docs/native-modules-ios
+- **Native Modules Android**: https://reactnative.dev/docs/native-modules-android
+
+---
+
+## ✅ Checklist
+
+- [ ] Install `react-native-demo-library-by-rinkal` in Container App
+- [ ] Import `ContainerCommunication` in Container App
+- [ ] Set up event listeners using `useEffect`
+- [ ] Don't forget to cleanup (`.remove()`) when component unmounts
+- [ ] Use MiniApp components (TaskCard) - they automatically send events
+- [ ] Test by clicking TaskCard and see events in Container
+
+---
+
+## 🐛 Troubleshooting
+
+### Events not received?
+1. Make sure you're using `ContainerCommunication.listenFromMiniApp()` or the helper methods
+2. Check that the event names match exactly
+3. Verify the listener is set up before the MiniApp sends events
+4. Check console logs for any errors
+
+### Multiple events received?
+- Make sure you're cleaning up listeners in the `return` of `useEffect`
+
+---
+
+## 💡 Tips
+
+1. **Always cleanup listeners** when component unmounts to prevent memory leaks
+2. **Use specific event names** to make debugging easier
+3. **Check console logs** - both MiniApp and Container log all communication
+4. **Test incrementally** - start with one event type, then add more
+
+---
+
+## 📞 Need Help?
+
+Check the examples in:
+- `CommunicationExample.tsx` - See working examples
+- `QUICK_REFERENCE.md` - Quick code snippets
+- `COMMUNICATION_DOCS.md` - Detailed documentation
+
+---
+
+**Ready to use! 🎉** Copy the code above into your Container App and start receiving events from the MiniApp!