@ngenux/ngage-whiteboarding 1.0.1 → 1.0.3

package/README.md

@@ -15,18 +15,102 @@ A React component library for creating collaborative whiteboards with real-time
 - ⚡ **Real-time sync** - Ultra-smooth 60fps collaborative drawing experience
 - 🎯 **TypeScript support** - Fully typed for better development experience
 
+## 📋 Prerequisites
+
+This package requires the following dependencies in your project:
+
+- **React** 16.8+ (with Hooks support)
+- **Tailwind CSS** 3.0+ (for styling)
+- **Vite** or similar modern bundler (recommended)
+
+### Optional but Recommended:
+- **shadcn/ui** setup for consistent design system
+
 ## 📦 Installation
 
+### Step 1: Install the Package
+
 ```bash
 npm install @ngenux/ngage-whiteboarding
 ```
 
+### Step 2: Setup Tailwind CSS (if not already installed)
+
+```bash
+npm install -D tailwindcss postcss autoprefixer
+npx tailwindcss init -p
+```
+
+### Step 3: Configure Tailwind
+
+Update your `tailwind.config.js` to include the package components:
+
+```js
+/** @type {import('tailwindcss').Config} */
+module.exports = {
+  content: [
+    "./src/**/*.{js,ts,jsx,tsx}",
+    "./node_modules/@ngenux/ngage-whiteboarding/**/*.{js,jsx,ts,tsx}",
+  ],
+  theme: {
+    extend: {},
+  },
+  plugins: [],
+}
+```
+
+### Step 4: Import Styles
+
+Add the package CSS to your main CSS file or import it in your main component:
+
+```css
+/* In your main CSS file (e.g., src/index.css) */
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+```
+
+```tsx
+// Or import in your main component
+import '@ngenux/ngage-whiteboarding/dist/styles.css';
+```
+
+### Step 5: Verify Setup
+
+Create a simple test component to verify everything is working:
+
+```tsx
+import React from 'react';
+import '@ngenux/ngage-whiteboarding/dist/styles.css';
+import { WhiteboardProvider, Whiteboard } from '@ngenux/ngage-whiteboarding';
+
+function TestWhiteboard() {
+  return (
+    <div style={{ width: '100vw', height: '100vh' }}>
+      <WhiteboardProvider webSocketUrl="ws://localhost:3001">
+        <Whiteboard
+          roomId="test-room"
+          userId="test-user"
+          isAdmin={true}
+          allowedUsers={['test-user']}
+        />
+      </WhiteboardProvider>
+    </div>
+  );
+}
+
+export default TestWhiteboard;
+```
+
+If you see a styled whiteboard with a toolbar and sidebar, your setup is complete! 🎉
+
 ## 🚀 Quick Start
 
 ### Basic Setup
 
 ```tsx
 import React from 'react';
+import '@ngenux/ngage-whiteboarding/dist/styles.css'; // Import the CSS
 import { WhiteboardProvider, Whiteboard } from '@ngenux/ngage-whiteboarding';
 
 function App() {
@@ -45,6 +129,36 @@ function App() {
 export default App;
 ```
 
+### For Vite Projects
+
+If you're using Vite, make sure your `vite.config.js` includes:
+
+```js
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+
+export default defineConfig({
+  plugins: [react()],
+  css: {
+    postcss: './postcss.config.js', // Ensure PostCSS is configured
+  },
+})
+```
+
+### For shadcn/ui Projects
+
+If you're using shadcn/ui, you can enhance the integration with our utility functions:
+
+```tsx
+import { cn } from '@ngenux/ngage-whiteboarding'; // Use our cn utility
+
+// Or use with your existing shadcn/ui cn function
+import { cn } from '@/lib/utils';
+import { Whiteboard } from '@ngenux/ngage-whiteboarding';
+
+const customClasses = cn('your-custom-classes', 'conditional-class');
+```
+
 ### Advanced Usage with Multiple Rooms
 
 ```tsx
@@ -76,6 +190,100 @@ function CollaborativeApp() {
 }
 ```
 
+### Transparent Background Configuration
+
+If you want to enforce a transparent background and prevent users from changing it:
+
+```tsx
+import { WhiteboardProvider, Whiteboard } from '@ngenux/ngage-whiteboarding';
+
+function TransparentWhiteboard() {
+  return (
+    <WhiteboardProvider webSocketUrl="ws://localhost:3001">
+      <Whiteboard
+        roomId="transparent-room"
+        userId="user-123"
+        isAdmin={true}
+        allowedUsers={['user-123']}
+        transparentBackground={true} // Forces transparent & locks background
+      />
+    </WhiteboardProvider>
+  );
+}
+```
+
+**Behavior:**
+- When `transparentBackground={true}`: 
+  - ✅ Background is automatically set to transparent
+  - 🔒 Background color picker is disabled and shows "Transparent background locked"
+  - Perfect for overlaying the whiteboard on existing content
+  
+- When `transparentBackground={false}` (default):
+  - ✅ Background defaults to white
+  - 🎨 Users can change background color freely
+
+### Video Background for Annotation
+
+Annotate over live video streams (screen-share, webcam, etc.):
+
+```tsx
+import { WhiteboardProvider, Whiteboard } from '@ngenux/ngage-whiteboarding';
+import { useEffect, useState } from 'react';
+
+function VideoAnnotationWhiteboard() {
+  const [videoStream, setVideoStream] = useState<MediaStream | undefined>();
+
+  // Get screen share or webcam stream
+  useEffect(() => {
+    async function getStream() {
+      try {
+        // Screen share example
+        const stream = await navigator.mediaDevices.getDisplayMedia({
+          video: { width: 1920, height: 1080 }
+        });
+        setVideoStream(stream);
+      } catch (err) {
+        console.error('Failed to get video stream:', err);
+      }
+    }
+    getStream();
+
+    return () => {
+      // Cleanup: stop all tracks when component unmounts
+      if (videoStream) {
+        videoStream.getTracks().forEach(track => track.stop());
+      }
+    };
+  }, []);
+
+  return (
+    <WhiteboardProvider webSocketUrl="ws://localhost:3001">
+      <Whiteboard
+        roomId="video-annotation-room"
+        userId="user-123"
+        isAdmin={true}
+        allowedUsers={['user-123']}
+        videoStream={videoStream} // Video renders as background layer
+      />
+    </WhiteboardProvider>
+  );
+}
+```
+
+**Features:**
+- 🎥 **Video as background**: Stream renders behind whiteboard canvas
+- 🖊️ **Draw over video**: All drawing tools work normally over the video
+- 🔒 **Auto-transparent**: Background automatically set to transparent
+- ⚡ **60fps performance**: HTML video layer, no canvas copying
+- 📐 **Auto-scaling**: Video maintains aspect ratio with letterbox
+- 🎯 **Pointer-events handled**: Video doesn't interfere with drawing
+
+**Use cases:**
+- Screen-share annotation for remote presentations
+- Video call annotation
+- Educational content markup
+- Live streaming annotation
+
 ## 📝 API Reference
 
 ### WhiteboardProvider Props
@@ -93,6 +301,8 @@ function CollaborativeApp() {
 | `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 |
+| `transparentBackground` | `boolean` | ❌ | `false` | Forces transparent background and disables color picker |
+| `videoStream` | `MediaStream` | ❌ | `undefined` | Live video stream for background layer (screen-share/video annotation) |
 
 ### Hooks
 
@@ -167,6 +377,8 @@ const MyWhiteboard: React.FC<WhiteboardProps> = (props) => {
 - Safari 13+
 - Edge 80+
 
+**Note:** Requires a modern browser with WebSocket support and ES6+ features.
+
 ## 📱 Responsive Design
 
 The whiteboard automatically adapts to different screen sizes and supports touch interactions on mobile devices.
@@ -182,19 +394,31 @@ The whiteboard automatically adapts to different screen sizes and supports touch
 
 ### Common Issues
 
-1. **WebSocket connection fails**
+1. **Styles not appearing / Components look unstyled**
+   - ✅ Ensure Tailwind CSS is installed and configured in your project
+   - ✅ Add the package path to your `tailwind.config.js` content array
+   - ✅ Import the package CSS: `import '@ngenux/ngage-whiteboarding/dist/styles.css'`
+   - ✅ Verify your PostCSS configuration is working
+
+2. **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**
+3. **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**
+4. **TypeScript errors**
    - Make sure you're importing types correctly
    - Verify your TypeScript configuration includes the package types
+   - Ensure React types are properly installed
+
+5. **Build errors with Vite/bundler**
+   - Update to the latest version of your bundler
+   - Ensure PostCSS and Tailwind plugins are properly configured
+   - Check that the package is included in your bundler's dependency optimization
 
 ## 📄 License
 

package/dist/index.d.ts

@@ -1,8 +1,10 @@
+import './src/styles.css';
 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';
+import { cn } from './src/lib/utils';
+export { Whiteboard, WhiteboardProvider, useCapture as useWhiteboardStream, cn };
+export type { WhiteboardProps } from './src/components/Whiteboard/index';
 export type { ShapeProps, ToolType, StrokeStyle, WhiteboardState, DrawingAction, CompressedData } from './src/types';
 export interface WhiteboardProviderProps {
     children: React.ReactNode;

package/dist/index.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.tsx"],"names":[],"mappings":"AAAA,OAAO,kBAAkB,CAAC;AAC1B,OAAO,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AACzD,OAAO,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AACrE,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACpD,OAAO,EAAE,EAAE,EAAE,MAAM,iBAAiB,CAAC;AAErC,OAAO,EAAE,UAAU,EAAE,kBAAkB,EAAE,UAAU,IAAI,mBAAmB,EAAE,EAAE,EAAE,CAAC;AAGjF,YAAY,EAAE,eAAe,EAAE,MAAM,mCAAmC,CAAC;AACzE,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"}