realtimecursor/docs/react-integration.md

Real-time collaboration system with cursor tracking and approval workflow

# React Integration Guide

This guide explains how to use RealtimeCursor in your React projects.

## Installation

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

## Basic Usage

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

function MyEditor() {
  const { 
    cursors, 
    updateCursor, 
    updateContent,
    collaborators 
  } = useRealtimeCursor({
    apiUrl: 'https://api.realtimecursor.com',
    projectId: 'my-project',
    user: {
      id: 'user-123',
      name: 'John Doe'
    }
  });

  // Your component code
}
```

## useRealtimeCursor Hook

The `useRealtimeCursor` hook provides all the functionality needed for real-time collaboration.

### Parameters

```jsx
const cursorState = useRealtimeCursor({
  apiUrl,      // URL of the RealtimeCursor server
  projectId,   // ID of the project
  user: {      // Current user information
    id,        // User ID
    name,      // User name
    color      // User color (optional)
  },
  autoConnect  // Whether to connect automatically (default: false)
});
```

### Return Values

```jsx
const {
  // Connection
  connect,              // Function to connect to the server
  disconnect,           // Function to disconnect from the server
  isConnected,          // Boolean indicating connection status
  
  // Cursor tracking
  cursors,              // Object containing all cursors
  updateCursor,         // Function to update cursor position
  
  // Content collaboration
  updateContent,        // Function to update content
  
  // User presence
  collaborators,        // Array of collaborators
  
  // Typing indicators
  setTyping,            // Function to set typing status
  typingUsers           // Array of users who are typing
} = useRealtimeCursor(options);
```

## CursorOverlay Component

The `CursorOverlay` component renders cursors for all collaborators.

```jsx
<CursorOverlay 
  cursors={cursors}           // Cursors from useRealtimeCursor
  containerRef={editorRef}    // Reference to the editor container (optional)
  renderCursor={customRender} // Custom cursor renderer (optional)
/>
```

## Complete Example

```jsx
import React, { useState, useRef, useEffect } 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,
    collaborators,
    connect,
    disconnect
  } = useRealtimeCursor({
    apiUrl: 'https://api.realtimecursor.com',
    projectId: 'my-project',
    user: {
      id: 'user-123',
      name: 'John Doe'
    }
  });

  // Connect on mount
  useEffect(() => {
    connect();
    return () => disconnect();
  }, [connect, disconnect]);
  
  const handleMouseMove = (e) => {
    if (!editorRef.current) return;
    
    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);
  };

  return (
    <div className="editor-container">
      <div className="collaborators">
        {collaborators.map(user => (
          <div key={user.id} className="collaborator">
            {user.name}
          </div>
        ))}
      </div>
      
      <textarea
        ref={editorRef}
        value={content}
        onChange={handleChange}
        onMouseMove={handleMouseMove}
      />
      
      <CursorOverlay cursors={cursors} />
    </div>
  );
}
```

## Custom Cursor Rendering

You can customize cursor rendering:

```jsx
<CursorOverlay
  cursors={cursors}
  renderCursor={(cursor) => (
    <div className="custom-cursor">
      <div 
        className="cursor-pointer" 
        style={{ backgroundColor: cursor.user.color }}
      />
      <div 
        className="cursor-label"
        style={{ backgroundColor: cursor.user.color }}
      >
        {cursor.user.name}
      </div>
    </div>
  )}
/>
```

## Server Configuration

By default, the SDK connects to the public RealtimeCursor server. For self-hosting:

```jsx
useRealtimeCursor({
  apiUrl: 'http://your-server-url:3000',
  // other options
});
```