@user-intent-detector/react/README.md

React bindings for the user-intent-detector core library, providing hooks and components to detect user intent like exit, conversion, hesitation, and confusion.

# @user-intent-detector/react

React hook for detecting user intent signals like exit, idle, hesitation, confusion, engagement, and more — powered by the core logic from `@user-intent-detector/core`.

## Features

- 🔍 Detects user exit, idle, confusion, hesitation, and engagement
- 🧠 Returns confidence score and idle time
- ⚙️ Configurable and extensible with callbacks
- 📦 Lightweight and tree-shakable
- 🧪 Optional debug mode

## Installation

```bash
npm install @user-intent-detector/react
# or
yarn add @user-intent-detector/react
```

> ⚠️ This package depends on `@user-intent-detector/core`, which will be installed automatically.

## Usage

```tsx
import { useUserIntent } from '@user-intent-detector/react';

function App() {
  const intent = useUserIntent({
    onExit: (data) => console.log('Exit intent!', data),
    onIdle: (data) => console.log('User idle:', data),
    onConfused: (data) => console.log('User confused:', data),
    onHesitation: (data) => console.log('User hesitation:', data),
    onEngaged: (data) => console.log('User engaged:', data),
    debug: true,
  });

  return (
    <div>
      <h1>User Intent: {intent.intent}</h1>
      <p>Confidence: {Math.round(intent.confidence * 100)}%</p>
      <p>Idle Time: {intent.idleTime}ms</p>
    </div>
  );
}
```

## Hook API

```ts
function useUserIntent(options?: UseUserIntentOptions): IntentData
```

### `UseUserIntentOptions`

| Option         | Type                      | Description                                                         |
|----------------|---------------------------|---------------------------------------------------------------------|
| `onExit`       | `(data) => void`          | Triggered when exit intent is detected                             |
| `onIdle`       | `(data) => void`          | Triggered when user goes idle (default 10s, configurable)          |
| `onBrowsing`   | `(data) => void`          | Triggered when user resumes normal browsing                        |
| `onConfused`   | `(data) => void`          | Triggered when user is detected as confused                        |
| `onHesitation` | `(data) => void`          | Triggered when user hesitates before clicking or action            |
| `onEngaged`    | `(data) => void`          | Triggered when user shows strong engagement (scroll, click, etc.)  |
| `idleTimeout`  | `number`                  | Timeout (in ms) for idle detection. Default: `10000` (10s)         |
| `debug`        | `boolean`                 | Enable console logs for debugging                                  |

### `IntentData`

```ts
interface IntentData {
  intent: 'browsing' | 'idle' | 'exiting' | 'confused' | 'hesitation' | 'engaged';
  confidence: number; // 0.0 to 1.0
  idleTime: number;   // In milliseconds
  timestamp: number;  // Unix timestamp in ms
}
```

## Example Use Cases

- Show exit-intent popup before user leaves
- Save form state when idle detected
- Highlight buttons when hesitation is high
- Offer help when confusion is detected
- Trigger personalization on engagement

## License

MIT © [Your Name or Org]
```