realtimecursor/README-NPM.md

Real-time collaboration system with cursor tracking and approval workflow

# RealtimeCursor

A lightweight library for real-time cursor tracking and collaboration in web applications.

## Quick Start

### Option 1: Use the npm package

```bash
npm install realtimecursor
```

```javascript
import { RealtimeCursor } from 'realtimecursor';

const cursor = new RealtimeCursor({
  projectId: 'your-project-id',
  user: {
    id: 'user-123',
    name: 'John Doe',
    color: '#3b82f6'
  }
});

cursor.connect();
```

### Option 2: Use the CDN

```html
<script src="https://cdn.jsdelivr.net/npm/realtimecursor@1.0.0/dist/index.js"></script>
<script>
  const cursor = new realtimecursor.RealtimeCursor({
    projectId: 'your-project-id',
    user: {
      id: 'user-123',
      name: 'John Doe',
      color: '#3b82f6'
    }
  });
  
  cursor.connect();
</script>
```

## Features

- 🖱️ Real-time cursor tracking
- 👥 Collaborator presence
- 📝 Content synchronization
- ⌨️ Typing indicators
- 🔄 Automatic reconnection
- 🎨 Customizable cursors and colors

## Demo

Open [https://realtimecursor-demo.onrender.com](https://realtimecursor-demo.onrender.com) in multiple browser windows to see the real-time collaboration in action.

## Usage

### Basic Usage

```javascript
import { RealtimeCursor } from 'realtimecursor';

// Initialize the cursor client
const cursor = new RealtimeCursor({
  projectId: 'your-project-id',
  user: {
    id: 'user-123',
    name: 'John Doe',
    color: '#3b82f6'
  }
});

// Connect to the real-time service
cursor.connect();

// Set up event handlers
cursor.on('connect', () => {
  console.log('Connected to real-time service');
});

cursor.on('collaborators-changed', (collaborators) => {
  console.log('Active collaborators:', collaborators);
});

cursor.on('cursors-changed', (cursors) => {
  console.log('Cursor positions:', cursors);
});

// Update cursor position
document.addEventListener('mousemove', (e) => {
  const editorElement = document.getElementById('editor');
  const rect = editorElement.getBoundingClientRect();
  
  cursor.updateCursor({
    x: e.clientX,
    y: e.clientY,
    relativeX: e.clientX - rect.left,
    relativeY: e.clientY - rect.top
  });
});

// Update content
document.getElementById('editor').addEventListener('input', (e) => {
  cursor.updateContent(e.target.value);
  cursor.updateTypingStatus(true);
  
  // Reset typing status after 2 seconds
  setTimeout(() => {
    cursor.updateTypingStatus(false);
  }, 2000);
});

// Disconnect when done
window.addEventListener('beforeunload', () => {
  cursor.disconnect();
});
```

### React Hook

```jsx
import React, { useState, useRef, useEffect } from 'react';
import { useRealtimeCursor } from 'realtimecursor';

function CollaborativeEditor() {
  const [content, setContent] = useState('');
  const editorRef = useRef(null);
  
  const { 
    cursors, 
    collaborators,
    connected,
    typingStatus,
    connect,
    disconnect,
    updateCursor, 
    updateContent,
    updateTypingStatus
  } = useRealtimeCursor({
    projectId: 'your-project-id',
    user: {
      id: 'user-123',
      name: 'John Doe',
      color: '#3b82f6'
    }
  });

  // Connect on mount
  useEffect(() => {
    connect();
    return () => disconnect();
  }, [connect, disconnect]);

  // Update cursor position on mouse move
  const handleMouseMove = (e) => {
    if (!editorRef.current) return;
    
    const rect = editorRef.current.getBoundingClientRect();
    updateCursor({
      x: e.clientX,
      y: e.clientY,
      relativeX: e.clientX - rect.left,
      relativeY: e.clientY - rect.top
    });
  };

  // Update content when changed
  const handleContentChange = (e) => {
    const newContent = e.target.value;
    setContent(newContent);
    updateContent(newContent);
    updateTypingStatus(true);
    
    // Reset typing status after 2 seconds
    setTimeout(() => updateTypingStatus(false), 2000);
  };

  return (
    <div>
      <div>Connection status: {connected ? 'Connected' : 'Disconnected'}</div>
      <div>Active collaborators: {collaborators.length}</div>
      
      <div 
        ref={editorRef} 
        onMouseMove={handleMouseMove}
        style={{ position: 'relative' }}
      >
        <textarea
          value={content}
          onChange={handleContentChange}
          placeholder="Start typing..."
        />
        
        {/* Render cursors */}
        {Object.values(cursors).map(cursor => (
          <div
            key={cursor.id}
            style={{
              position: 'absolute',
              left: cursor.position.x || cursor.position.relativeX || 0,
              top: cursor.position.y || cursor.position.relativeY || 0,
              pointerEvents: 'none'
            }}
          >
            <div
              style={{
                backgroundColor: cursor.user.color || '#3b82f6',
                padding: '2px 6px',
                borderRadius: '4px',
                color: 'white',
                fontSize: '12px'
              }}
            >
              {cursor.user.name}
              {typingStatus[cursor.id]?.isTyping && ' (typing...)'}
            </div>
          </div>
        ))}
      </div>
    </div>
  );
}
```

## API Reference

See the [full documentation](https://github.com/yourusername/realtimecursor/blob/main/npm-package/README.md) for detailed API reference.

## License

MIT