@ngenux/ngage-whiteboarding 1.0.0

package/README.md

@@ -0,0 +1,249 @@
+# React Collaborative Whiteboard
+
+A React component library for creating collaborative whiteboards with real-time synchronization via WebSockets.
+
+## ✨ Features
+
+- 🎨 **Real-time collaborative drawing** - Multiple users can draw simultaneously
+- 🔧 **Multiple drawing tools** - Pencil, shapes (rectangle, ellipse, arrow), eraser, line tools
+- ↩️ **Undo/Redo functionality** - Per-user undo/redo with collaborative support
+- 👥 **Multi-user support** - Admin controls and user permissions
+- 📱 **Responsive design** - Works on desktop, tablet, and mobile
+- 🔒 **Admin controls** - Lock/unlock canvas, clear canvas, user management
+- 💾 **Export functionality** - PNG, JPEG, PDF export options
+- 🗜️ **Data compression** - Optimized performance with automatic compression
+- ⚡ **Real-time sync** - Ultra-smooth 60fps collaborative drawing experience
+- 🎯 **TypeScript support** - Fully typed for better development experience
+
+## 📦 Installation
+
+```bash
+npm install @ngenux/ngage-whiteboarding
+```
+
+## 🚀 Quick Start
+
+### Basic Setup
+
+```tsx
+import React from 'react';
+import { WhiteboardProvider, Whiteboard } from '@ngenux/ngage-whiteboarding';
+
+function App() {
+  return (
+    <WhiteboardProvider webSocketUrl="ws://localhost:3001">
+      <Whiteboard
+        roomId="room-123"
+        userId="user-456"
+        isAdmin={true}
+        allowedUsers={['user-456', 'user-789']}
+      />
+    </WhiteboardProvider>
+  );
+}
+
+export default App;
+```
+
+### Advanced Usage with Multiple Rooms
+
+```tsx
+import React, { useState } from 'react';
+import { WhiteboardProvider, Whiteboard } from '@ngenux/ngage-whiteboarding';
+
+function CollaborativeApp() {
+  const [currentRoom, setCurrentRoom] = useState('room-1');
+  const [currentUser] = useState('user-' + Math.random().toString(36).substr(2, 9));
+
+  return (
+    <WhiteboardProvider webSocketUrl="wss://your-websocket-server.com">
+      <div>
+        <select value={currentRoom} onChange={(e) => setCurrentRoom(e.target.value)}>
+          <option value="room-1">Room 1</option>
+          <option value="room-2">Room 2</option>
+          <option value="room-3">Room 3</option>
+        </select>
+        
+        <Whiteboard
+          roomId={currentRoom}
+          userId={currentUser}
+          isAdmin={currentUser === 'admin-user'}
+          allowedUsers={[currentUser, 'other-user-1', 'other-user-2']}
+        />
+      </div>
+    </WhiteboardProvider>
+  );
+}
+```
+
+## 📝 API Reference
+
+### WhiteboardProvider Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `webSocketUrl` | `string` | ✅ | WebSocket server URL for real-time collaboration |
+| `children` | `ReactNode` | ✅ | Child components (typically contains `<Whiteboard>`) |
+
+### Whiteboard Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `roomId` | `string` | ✅ | - | Unique identifier for the collaboration room |
+| `userId` | `string` | ✅ | - | Unique identifier for the current user |
+| `isAdmin` | `boolean` | ❌ | `false` | Whether user has admin privileges (clear, lock/unlock) |
+| `allowedUsers` | `string[]` | ❌ | `[]` | Array of user IDs who have drawing permissions |
+
+### Hooks
+
+#### useWhiteboardStream
+
+Automatically captures the whiteboard canvas as a video stream (30 FPS). No manual start/stop controls needed.
+
+```tsx
+import { useWhiteboardStream } from '@ngenux/ngage-whiteboarding';
+
+function VideoStreamComponent() {
+  const { mediaStream } = useWhiteboardStream();
+  
+  return (
+    <div>
+      {mediaStream && (
+        <video 
+          srcObject={mediaStream} 
+          autoPlay 
+          muted 
+          style={{ width: '300px', height: '200px' }}
+        />
+      )}
+    </div>
+  );
+}
+```
+
+**Note:** Stream capture starts automatically when the whiteboard canvas is available and can be controlled via the whiteboard context's `captureEnabled` state.
+
+## 🎨 Features in Detail
+
+### Drawing Tools
+- **Pencil**: Freehand drawing
+- **Shapes**: Rectangle, Ellipse, Arrow, Line
+- **Eraser**: Remove parts of drawings
+- **Select**: Move and transform shapes
+- **Pan**: Navigate around the canvas
+
+### Collaborative Features
+- **Real-time drawing**: See other users draw in real-time
+- **User permissions**: Control who can draw
+- **Admin controls**: Lock/unlock canvas, clear all drawings
+- **Per-user undo/redo**: Each user maintains their own undo stack
+
+### Export Options
+- **PNG**: Transparent or solid background
+- **JPEG**: Solid background (white if transparent is selected)
+- **PDF-format**: High-quality PNG optimized for printing/PDF conversion
+
+## 🛠️ Development
+
+### Building the Package
+
+```bash
+# Install dependencies
+npm install
+
+# Build the package
+npm run build
+
+# Watch mode for development
+npm run dev
+
+# Preview package contents
+npm run pack-preview
+
+# Clean build artifacts
+npm run clean
+```
+
+### Package Structure
+
+```
+dist/
+├── index.js          # CommonJS build
+├── index.esm.js      # ES modules build
+├── index.d.ts        # TypeScript definitions
+└── *.map            # Source maps
+```
+
+## 🔧 TypeScript Support
+
+The package includes full TypeScript definitions:
+
+```tsx
+import type { 
+  WhiteboardProps, 
+  WhiteboardProviderProps,
+  ToolType, 
+  StrokeStyle 
+} from '@ngenux/ngage-whiteboarding';
+
+const MyWhiteboard: React.FC<WhiteboardProps> = (props) => {
+  // Your implementation
+};
+```
+
+## 🌐 Browser Support
+
+- Chrome 80+
+- Firefox 75+
+- Safari 13+
+- Edge 80+
+
+## 📱 Responsive Design
+
+The whiteboard automatically adapts to different screen sizes and supports touch interactions on mobile devices.
+
+## ⚡ Performance
+
+- **Optimized rendering**: Uses Konva.js for high-performance 2D canvas rendering
+- **Data compression**: Automatic compression of collaborative data
+- **Throttled updates**: Optimized for 60fps real-time collaboration
+- **Memory efficient**: Smart cleanup of stale collaborative data
+
+## 🐛 Troubleshooting
+
+### Common Issues
+
+1. **WebSocket connection fails**
+   - Ensure your WebSocket server is running and accessible
+   - Check CORS configuration on your server
+   - Verify the `webSocketUrl` is correct
+
+2. **Drawing doesn't sync between users**
+   - Verify all users are in the same `roomId`
+   - Check WebSocket server is properly broadcasting messages
+   - Ensure `userId` is unique for each user
+
+3. **TypeScript errors**
+   - Make sure you're importing types correctly
+   - Verify your TypeScript configuration includes the package types
+
+## 📄 License
+
+MIT
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## 📞 Support
+
+If you encounter any issues or have questions, please file an issue on the GitHub repository.
+
+---
+
+## 👨‍💻 Author
+
+**ng-sushil**
+- GitHub: [@ng-sushil](https://github.com/ng-sushil)
+
+**Happy collaborating! 🎨✨** 

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+import { Whiteboard } from './src/components/Whiteboard';
+import { WhiteboardProvider } from './src/context/WhiteboardContext';
+import { useCapture } from './src/hooks/useCapture';
+export { Whiteboard, WhiteboardProvider, useCapture as useWhiteboardStream };
+export type { WhiteboardProps } from './src/components/Whiteboard';
+export type { ShapeProps, ToolType, StrokeStyle, WhiteboardState, DrawingAction, CompressedData } from './src/types';
+export interface WhiteboardProviderProps {
+    children: React.ReactNode;
+    webSocketUrl?: string;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AACzD,OAAO,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AACrE,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAEpD,OAAO,EAAE,UAAU,EAAE,kBAAkB,EAAE,UAAU,IAAI,mBAAmB,EAAE,CAAC;AAG7E,YAAY,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AACnE,YAAY,EACV,UAAU,EACV,QAAQ,EACR,WAAW,EACX,eAAe,EACf,aAAa,EACb,cAAc,EACf,MAAM,aAAa,CAAC;AAGrB,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB"}