smart-idle/README.md

Lightweight browser library to detect user inactivity with event dispatching

# 💤 smart-idle

**smart-idle** is a lightweight, customizable JavaScript library that detects user inactivity (idle state) in the browser. It helps you implement features like auto-logout, UI hiding, session timeout, or analytics triggers with ease.

- 🔧 Framework-agnostic (works with React, Vue, Angular, Vanilla JS, etc.)
- 🎛️ Fully customizable idle timeout and activity events
- 💡 Built-in event listeners and manual control methods
- 🧪 Minimal dependencies and small size

---


## 📦 Installation

### Using npm

```
npm install smart-idle
```

### Using CDN (for browser use)

```
<script type="module">
  import { SmartIdle } from 'https://cdn.jsdelivr.net/npm/smart-idle/+esm';

  const idle = new SmartIdle({ timeout: 10000 });
  idle.start();
</script>
```

---


## 🚀 Getting Started

### Basic Example

```
import { SmartIdle } from 'smart-idle';

const idle = new SmartIdle({
  timeout: 60000, // 1 minute
  onIdle: () => console.log('User is idle'),
  onActive: () => console.log('User is active again'),
});

idle.start();
```

---


## ⚙️ Configuration Options

When you create a `SmartIdle` instance, you can pass these options:

| Option     | Type       | Default                     | Description                              |
|------------|------------|-----------------------------|------------------------------------------|
| `timeout`  | `number`   | `60000` (ms)                | Time (in milliseconds) before becoming idle |
| `onIdle`   | `Function` | `() => {}`                  | Callback fired when user becomes idle    |
| `onActive` | `Function` | `() => {}`                  | Callback fired when user returns         |
| `events`   | `string[]` | See below                   | DOM events to listen to                  |

### Default `events` listened to:

```
[
  'mousemove',
  'scroll',
  'keydown',
  'touchstart',
  'visibilitychange'
]
```

You can override this like so:

```
const idle = new SmartIdle({
  timeout: 15000,
  events: ['click', 'keydown', 'pointermove'], // custom events
});
```

---


## 📚 API Reference

| Method           | Description                                     |
|------------------|-------------------------------------------------|
| `start()`        | Start tracking user activity                    |
| `stop()`         | Stop tracking and clear timers                  |
| `pause()`        | Temporarily pause idle tracking                 |
| `resume()`       | Resume tracking after pause                     |
| `reset()`        | Reset the internal idle timer                   |
| `destroy()`      | Remove all listeners and stop everything        |
| `triggerIdle()`  | Manually set the state to idle immediately      |

---


## 💡 Use Cases

- 🔐 Auto logout users after inactivity  
- 🛑 Pause video/audio when the user is idle  
- 🧼 Dim or hide UI after a period of no input  
- 📊 Trigger analytics or session tracking  
- 📉 Conserve resources in low-interaction tabs  

---


## 🔌 Framework Examples

### React

```
useEffect(() => {
  const idle = new SmartIdle({
    timeout: 10000,
    onIdle: () => console.log('Idle'),
    onActive: () => console.log('Active'),
  });

  idle.start();
  return () => idle.destroy();
}, []);
```

### Vue (Composition API)

```
onMounted(() => {
  const idle = new SmartIdle({
    timeout: 10000,
    onIdle: () => console.log("Idle"),
    onActive: () => console.log("Back"),
  });
  idle.start();
});

onUnmounted(() => idle.destroy());
```

---


## 🖥️ CLI Support (Optional)

This package comes with a CLI entry point for developer information.

### Install globally:

```
npm install -g smart-idle
```

### Use:

```
smart-idle --help
```

> ⚠️ Note: The CLI is informational only; this is not a Node-based runtime tool.

---


## 🌐 Browser Compatibility

| Browser       | Supported |
|---------------|-----------|
| Chrome        | ✅        |
| Firefox       | ✅        |
| Safari        | ✅        |
| Edge          | ✅        |
| Internet Explorer | ❌    |

> This library is **not designed** for Node.js usage.

---


## 📝 License

MIT License © 2025 ward-00