realtimecursor/CURSOR_INTEGRATION_GUIDE.md

Real-time collaboration system with cursor tracking and approval workflow

# RealtimeCursor Integration Guide

This guide will help you integrate the RealtimeCursor SDK into your web application to enable real-time cursor tracking and collaboration features.

## Installation

Install the RealtimeCursor SDK using npm:

```bash
npm install realtimecursor-sdk
```

Or using yarn:

```bash
yarn add realtimecursor-sdk
```

## Basic Integration

### 1. Import the SDK

```javascript
// React
import { useRealtimeCursor, CursorOverlay } from 'realtimecursor-sdk';
import 'realtimecursor-sdk/dist/cursor.css';

// Vanilla JavaScript
import { RealtimeCursor } from 'realtimecursor-sdk';
import 'realtimecursor-sdk/dist/cursor.css';
```

### 2. Set Up the Server

The RealtimeCursor SDK requires a server that supports WebSockets. You can use the provided server implementation or create your own.

To use the provided server:

```bash
# Clone the repository
git clone https://github.com/sourabhpunase/realtimecursor.git

# Install dependencies
cd realtimecursor/api
npm install

# Start the server
npm start
```

The server will run on port 3000 by default.

### 3. React Integration

```jsx
import React, { useState, useRef } from 'react';
import { useRealtimeCursor, CursorOverlay } from 'realtimecursor-sdk';
import 'realtimecursor-sdk/dist/cursor.css';

function CollaborativeEditor() {
  const [content, setContent] = useState('');
  const editorRef = useRef(null);
  
  const { 
    cursors, 
    updateCursor, 
    updateContent,
    updateCursorPosition 
  } = useRealtimeCursor({
    apiUrl: 'http://localhost:3000',
    projectId: 'your-project-id',
    user: {
      id: 'user-123',
      name: 'John Doe'
    }
  });

  const handleMouseMove = (e) => {
    if (!editorRef.current) return;
    
    const rect = editorRef.current.getBoundingClientRect();
    updateCursor({
      x: e.clientX,
      y: e.clientY,
      textPosition: editorRef.current.selectionStart
    });
  };

  const handleChange = (e) => {
    const newContent = e.target.value;
    setContent(newContent);
    updateContent(newContent, e.target.selectionStart);
  };

  const handleSelect = () => {
    if (!editorRef.current) return;
    updateCursorPosition(editorRef.current.selectionStart);
  };

  return (
    <div className="editor-container">
      <textarea
        ref={editorRef}
        value={content}
        onChange={handleChange}
        onMouseMove={handleMouseMove}
        onSelect={handleSelect}
        className="editor"
      />
      
      {/* Render other users' cursors */}
      <CursorOverlay 
        cursors={cursors} 
        content={content} 
        editorRef={editorRef} 
      />
    </div>
  );
}
```

### 4. Vanilla JavaScript Integration

```javascript
import { RealtimeCursor } from 'realtimecursor-sdk';
import 'realtimecursor-sdk/dist/cursor.css';

// Initialize the cursor client
const cursorClient = new RealtimeCursor({
  apiUrl: 'http://localhost:3000',
  projectId: 'your-project-id',
  user: {
    id: 'user-123',
    name: 'John Doe'
  }
});

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

// Set up event handlers
cursorClient.onCursorUpdate = ({ socketId, user, x, y }) => {
  // Render cursor for this user
  renderCursor(socketId, user, x, y);
};

cursorClient.onContentUpdate = ({ content }) => {
  // Update editor content
  document.getElementById('editor').value = content;
};

// Update cursor position on mouse move
document.getElementById('editor').addEventListener('mousemove', (e) => {
  cursorClient.updateCursor({
    x: e.clientX,
    y: e.clientY
  });
});

// Update content on change
document.getElementById('editor').addEventListener('input', (e) => {
  cursorClient.updateContent(e.target.value);
});

// Clean up on page unload
window.addEventListener('beforeunload', () => {
  cursorClient.disconnect();
});
```

## Advanced Integration

### Using the CollaborativeTextarea Component

```jsx
import React, { useState } from 'react';
import { useRealtimeCursor, CollaborativeTextarea, CursorOverlay } from 'realtimecursor-sdk';
import 'realtimecursor-sdk/dist/cursor.css';

function SimpleEditor() {
  const [content, setContent] = useState('');
  const editorRef = useRef(null);
  
  const { 
    cursors, 
    updateCursor, 
    updateContent,
    updateCursorPosition,
    setTyping
  } = useRealtimeCursor({
    apiUrl: 'http://localhost:3000',
    projectId: 'your-project-id',
    user: {
      id: 'user-123',
      name: 'John Doe'
    }
  });

  return (
    <div className="editor-container">
      <CollaborativeTextarea
        value={content}
        onChange={(newContent) => {
          setContent(newContent);
          updateContent(newContent);
        }}
        onCursorMove={updateCursor}
        onCursorPositionChange={updateCursorPosition}
        onTypingStatusChange={setTyping}
        placeholder="Start typing to collaborate..."
      />
      
      <CursorOverlay 
        cursors={cursors} 
        content={content} 
        editorRef={editorRef} 
      />
    </div>
  );
}
```

### Showing Collaborators List

```jsx
import { CollaboratorsList } from 'realtimecursor-sdk';

function CollaborativeApp() {
  const { collaborators, typingUsers } = useRealtimeCursor({
    // ... options
  });

  return (
    <div>
      <CollaboratorsList 
        collaborators={collaborators} 
        typingUsers={typingUsers} 
      />
      {/* ... rest of your app */}
    </div>
  );
}
```

## API Reference

### RealtimeCursor Class

```typescript
new RealtimeCursor(options: RealtimeCursorOptions)
```

#### Options

- `apiUrl` (string): URL of your API server
- `socketUrl` (string, optional): URL of your WebSocket server (defaults to apiUrl)
- `projectId` (string): ID of the project to collaborate on
- `user` (object): Information about the current user
  - `id` (string): User ID
  - `name` (string): User name
  - `color` (string, optional): User cursor color (e.g., '#3b82f6')
- `token` (string, optional): Authentication token
- `autoConnect` (boolean, optional): Whether to connect automatically (default: true)

#### Methods

- `connect()`: Connect to the real-time service
- `disconnect()`: Disconnect from the real-time service
- `updateCursor(position)`: Update cursor position
- `updateCursorPosition(textPosition)`: Update cursor position in text
- `updateContent(content, cursorPosition?)`: Update content
- `setTyping(isTyping)`: Set typing indicator
- `getCollaborators()`: Get current collaborators
- `getCursors()`: Get current cursors
- `getTypingUsers()`: Get typing users

#### Event Handlers

- `onCollaboratorsChange`: Called when collaborators change
- `onUserJoined`: Called when a user joins
- `onUserLeft`: Called when a user leaves
- `onContentUpdate`: Called when content is updated
- `onCursorUpdate`: Called when a cursor is updated
- `onCursorPositionUpdate`: Called when a cursor position is updated
- `onTypingStatusChange`: Called when typing status changes

### React Hook: useRealtimeCursor

```typescript
const {
  collaborators,
  cursors,
  typingUsers,
  isConnected,
  connect,
  disconnect,
  updateCursor,
  updateCursorPosition,
  updateContent,
  setTyping,
  client
} = useRealtimeCursor(options)
```

### React Components

- `Cursor`: Displays a cursor at a specific position
- `TextCursor`: Displays a cursor at a specific text position
- `CursorOverlay`: Displays all cursors
- `CollaboratorsList`: Displays a list of collaborators
- `CollaborativeTextarea`: A textarea with real-time collaboration

## Customization

### Styling

You can customize the appearance of cursors and other components by overriding the CSS classes:

```css
/* Custom cursor styles */
.realtimecursor-cursor {
  /* Your styles here */
}

.realtimecursor-pointer {
  /* Your styles here */
}

.realtimecursor-name {
  /* Your styles here */
}

/* Custom collaborator list styles */
.realtimecursor-collaborators {
  /* Your styles here */
}

.realtimecursor-collaborator {
  /* Your styles here */
}

.realtimecursor-avatar {
  /* Your styles here */
}

.realtimecursor-typing-indicator {
  /* Your styles here */
}
```

## Troubleshooting

### Common Issues

1. **Cursors not showing**: Make sure you've imported the CSS file and added the `CursorOverlay` component.
2. **Connection issues**: Check that your server is running and accessible.
3. **Content not syncing**: Ensure you're calling `updateContent` when the content changes.

### Debugging

Enable debug mode to see more detailed logs:

```javascript
// React
const { client, ...rest } = useRealtimeCursor({
  // ... options
  debug: true
});

// Vanilla JavaScript
const cursorClient = new RealtimeCursor({
  // ... options
  debug: true
});
```

## Examples

For more examples, see the [examples directory](https://github.com/sourabhpunase/realtimecursor/tree/main/sdk/examples) in the repository.

## License

MIT