sticky-horse/README.md

With StickyHorse allow your users to send feedback to your team.

# Sticky Horse

A powerful real-time collaboration toolkit for React applications. Add cursor tracking, feedback systems, and real-time presence to your app in minutes.

## Features

- 👥 Real-time cursor tracking and sharing
- 💬 Interactive feedback system with comments
- 📝 Sticky notes for collaborative annotations
- 🎯 Laser pointer for presentations
- 👤 User presence tracking

## Installation

```bash
npm install @mohammedsaid/sticky-horse
# or
yarn add @mohammedsaid/sticky-horse
```

## Quick Start

1. Initialize StickyHorse in your app:

```typescript
import { initStickyHorse, StickyHorseProvider } from '@mohammedsaid/sticky-horse';
// Import the styles
import '@mohammedsaid/sticky-horse/dist/styles.css';

// Initialize with your API key (get it from the dashboard)
initStickyHorse({
  apiKey: 'your-api-key',
  socketUrl: 'your-socket-url',
  onUserJoin: (user) => {
    console.log('User joined:', user);
  },
  onUserLeave: (user) => {
    console.log('User left:', user);
  }
});

// Wrap your app with the provider
function App() {
  return (
    <StickyHorseProvider>
      <YourApp />
    </StickyHorseProvider>
  );
}
```

2. Add cursor tracking to any component:

```typescript
import { withTracking } from '@mohammedsaid/sticky-horse';

function YourComponent() {
  return <div>Your content here</div>;
}

export default withTracking(YourComponent, '/page-path');
```

3. Use the feedback system:

```typescript
import { UserFeedbackOverlay } from '@mohammedsaid/sticky-horse';

function YourPage() {
  return (
    <div>
      <YourContent />
      <UserFeedbackOverlay />
    </div>
  );
}
```

4. Access StickyHorse features in your components:

```typescript
import { useStickyHorse } from '@mohammedsaid/sticky-horse';

function YourComponent() {
  const { activeUsers, comments, stickyNotes, addComment } = useStickyHorse();

  return (
    <div>
      <h2>Active Users: {activeUsers.length}</h2>
      {/* Your UI */}
    </div>
  );
}
```

## Styles

StickyHorse uses Tailwind CSS for styling. Make sure to:

1. Import the styles in your app:
```typescript
import '@mohammedsaid/sticky-horse/dist/styles.css';
```

2. If you're using Tailwind CSS in your project, add StickyHorse to your content paths in `tailwind.config.js`:
```javascript
module.exports = {
  content: [
    // ... your other content paths
    './node_modules/@mohammedsaid/sticky-horse/dist/**/*.{js,jsx,ts,tsx}'
  ],
  // ... rest of your config
}
```

## API Reference

### Components

- `withTracking(Component, pagePath)`: HOC to add cursor tracking
- `UserFeedbackOverlay`: Component for feedback system
- `CursorOverlay`: Component for showing other users' cursors
- `LaserCursorTrail`: Component for laser pointer feature

### Hooks

- `useStickyHorse()`: Access all StickyHorse features
- `useCursorTracking()`: Hook for cursor tracking
- `usePageTracking()`: Hook for page presence

### Configuration

The `initStickyHorse` function accepts the following options:

```typescript
interface StickyHorseConfig {
  apiKey: string;
  socketUrl: string;
  onUserJoin?: (user: User) => void;
  onUserLeave?: (user: User) => void;
  onComment?: (comment: Comment) => void;
  onStickyNote?: (note: StickyNote) => void;
  onCursorMove?: (cursor: CursorData) => void;
}
```

## License

MIT