nova-hooks 2.0.2 → 2.0.7

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mohamed Jabarullah
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -1,52 +1,52 @@
-{
-  "name": "nova-hooks",
-  "version": "2.0.2",
-  "description": "Nova hooks package",
-  "keywords": [
-    "nova",
-    "hooks"
-  ],
-  "homepage": "https://github.com/mjjabarullah/nova-hooks#readme",
-  "bugs": {
-    "url": "https://github.com/mjjabarullah/nova-hooks/issues"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/mjjabarullah/nova-hooks.git"
-  },
-  "license": "ISC",
-  "author": "Mohamed Jabarullah",
-  "type": "module",
-  "main": "dist/index.cjs.js",
-  "module": "dist/index.es.js",
-  "types": "dist/index.d.ts",
-  "files": [
-    "dist"
-  ],
-  "scripts": {
-    "build": "vite build",
-    "prepare": "vite build",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "coverage": "vitest run --coverage"
-  },
-  "dependencies": {
-    "socket.io-client": "^4.8.3"
-  },
-  "peerDependencies": {
-    "react": "^18.0.0 || ^19.0.0"
-  },
-  "devDependencies": {
-    "@testing-library/jest-dom": "^6.9.1",
-    "@testing-library/react": "^16.3.2",
-    "@types/node": "^25.6.2",
-    "@types/react": "^19.2.14",
-    "@types/react-dom": "^19.2.3",
-    "@vitest/coverage-v8": "^3.2.4",
-    "jsdom": "^27.0.1",
-    "typescript": "~6.0.3",
-    "vite": "^8.0.12",
-    "vite-plugin-dts": "^5.0.0",
-    "vitest": "^3.2.4"
-  }
-}
+{
+  "name": "nova-hooks",
+  "version": "2.0.7",
+  "description": "Nova hooks package",
+  "keywords": [
+    "nova",
+    "hooks"
+  ],
+  "homepage": "https://github.com/mjjabarullah/nova-hooks#readme",
+  "bugs": {
+    "url": "https://github.com/mjjabarullah/nova-hooks/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mjjabarullah/nova-hooks.git"
+  },
+  "license": "MIT",
+  "author": "Mohamed Jabarullah",
+  "type": "module",
+  "main": "dist/index.cjs.js",
+  "module": "dist/index.es.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "vite build",
+    "prepare": "vite build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "coverage": "vitest run --coverage"
+  },
+  "dependencies": {
+    "socket.io-client": "^4.8.3"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
+    "@types/node": "^25.6.2",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@vitest/coverage-v8": "^3.2.4",
+    "jsdom": "^27.0.1",
+    "typescript": "~6.0.3",
+    "vite": "^8.0.12",
+    "vite-plugin-dts": "^5.0.0",
+    "vitest": "^3.2.4"
+  }
+}

package/readme.md

@@ -1,146 +1,146 @@
-# nova-hooks
-
-A highly-optimized, **zero-configuration** event tracking utility for capturing user interactions and page visits in React applications. Built with a custom, lightweight `EventBus` and `socket.io-client`.
-
----
-
-## ✨ Features
-
-- **Zero-Config Tracking:** Automatically captures clicks on buttons, links, and interactive elements without needing manual attributes!
-- **True Page Dwell Time:** Uses the native Page Visibility API to calculate the _actual_ active time spent on a page (pauses when the user switches tabs).
-- **Network Optimized:** Employs a built-in 1-second debouncing and click-batching mechanism to minimize network overhead.
-- **Ultra-Lightweight:** Zero dependencies (other than `socket.io-client`). Fully framework-agnostic core logic.
-- **Auto-Enriched Context:** Automatically attaches `PageUrl`, `PageTitle`, `Project`, and `CreatedDate` to every single event payload.
-- **SSR Safe:** Fully compatible with Next.js and Remix.
-
----
-
-## 🚀 Getting Started
-
-### 1. Install
-
-```bash
-yarn add nova-hooks
-```
-
-```bash
-npm i nova-hooks
-```
-
-### 2. Initialization
-
-> [!IMPORTANT]
-> Ensure the socket connection is established at the root of your application using the `connectSocket` method.
-
-```tsx
-import { connectSocket } from "nova-hooks";
-import { useEffect } from "react";
-
-const App = () => {
-  useEffect(() => {
-    connectSocket(import.meta.env.VITE_APP_SOCKET, "WolfPack");
-  }, []);
-
-  // app code...
-};
-```
-
----
-
-## 🛠️ Usage Examples
-
-### 1. Zero-Config Global Click Tracking
-
-Place `useGlobalClickTracker` in your authenticated layout. It will automatically listen to the DOM and seamlessly track clicks on any `<button>`, `<a>`, or `cursor: pointer` element!
-
-```tsx
-import { useGlobalClickTracker } from "nova-hooks";
-
-const ProtectedLayout = ({ children }) => {
-  const { user } = useAuth();
-
-  // Magic happens here! Tracks all UI clicks across the entire app.
-  useGlobalClickTracker(user?.empId, user?.roleId);
-
-  return <>{children}</>;
-};
-```
-
-_Note: It will intelligently extract labels from `innerText`, `title`, `aria-label`, or auto-generate a fallback CSS Path!_
-
-### 2. Explicit Tracking (Optional Overrides)
-
-If you want to override the auto-detected name for a specific button, just attach the `data-nova-*` attributes:
-
-```tsx
-<button
-  data-nova-track-id="Custom Task Action"
-  data-nova-track-type={ActionType.Button}
->
-  Track Me Specifically
-</button>
-```
-
-### 3. Accurate Page Dwell Time
-
-Track exactly how long a user actively stares at a specific page/component. The timer pauses if they switch tabs or minimize the browser!
-
-```tsx
-import { usePageTimeTracker } from "nova-hooks";
-
-export const Dashboard = () => {
-  const { user } = useAuth();
-
-  // Tracks active dwell time and emits it automatically when the user leaves the page
-  usePageTimeTracker("Home Dashboard", user?.empId, user?.roleId);
-
-  return <div>Welcome to the Dashboard</div>;
-};
-```
-
-### 4. Manual / Imperative Tracking
-
-If you need to track events programmatically (like inside an API success callback), use the `withEvent` method:
-
-```tsx
-import { withEvent, ActionType } from "nova-hooks";
-
-const doLogin = () => {
-  api.login().then(() => {
-    withEvent({
-      Action: "Login Success",
-      ActionType: ActionType.Login,
-      EmpId: "EMP-123",
-      EmpRole: "Admin",
-      Count: 1,
-    });
-  });
-};
-```
-
----
-
-## 📦 Exports & Types
-
-| Name                    | Type                                                         | Description                                                             |
-| ----------------------- | ------------------------------------------------------------ | ----------------------------------------------------------------------- |
-| `ActionType`            | `object`                                                     | Predefined enum-like values: `"Button"`, `"Menu"`, `"Login"`, `"Link"`  |
-| `PageVisitAction`       | `string`                                                     | Constant string `"Page Visit"` used for tracking page visits            |
-| `connectSocket`         | `(socketUrl: string, project: string) => void`               | Connects to the socket server and sets the project name.                |
-| `disconnectSocket`      | `() => void`                                                 | Disconnects and cleans up the active socket connection.                 |
-| `withEvent`             | `(eventData: EventData, callback?: Function) => void`        | Emits a structured event optionally after running a callback.           |
-| `useGlobalClickTracker` | `(empId?: string, roleId?: string) => void`                  | React hook to automatically track global click events.                  |
-| `usePageTimeTracker`    | `(action: string; empId?: string; empRole?: string) => void` | React hook to track active time spent on a page via the Visibility API. |
-
-### EventData Structure
-
-All events are automatically enriched with `Project`, `PageUrl`, `PageTitle`, and an ISO `CreatedDate`.
-
-| Property     | Type                                                              | Description                                                     |
-| ------------ | ----------------------------------------------------------------- | --------------------------------------------------------------- |
-| `ActionType` | `keyof typeof ActionType` \| `typeof PageVisitAction`             | Type of the action.                                             |
-| `Action`     | `string`                                                          | Specific action performed (extracted from DOM or manually set). |
-| `EmpId`      | `string`                                                          | Unique identifier of the employee.                              |
-| `EmpRole`    | `string`                                                          | Role of the employee performing the action.                     |
-| `Count`      | `number` _(only when `ActionType` is from `ActionType`)_          | Number of rapid occurrences of the action (batched).            |
-| `Duration`   | `number` _(seconds, only when `ActionType` is `PageVisitAction`)_ | Duration of the _active_ visit in seconds.                      |
+# nova-hooks
+
+A highly-optimized, **zero-configuration** event tracking utility for capturing user interactions and page visits in React applications. Built with a custom, lightweight `EventBus` and `socket.io-client`.
+
+---
+
+## ✨ Features
+
+- **Zero-Config Tracking:** Automatically captures clicks on buttons, links, and interactive elements without needing manual attributes!
+- **True Page Dwell Time:** Uses the native Page Visibility API to calculate the _actual_ active time spent on a page (pauses when the user switches tabs).
+- **Network Optimized:** Employs a built-in 1-second debouncing and click-batching mechanism to minimize network overhead.
+- **Ultra-Lightweight:** Zero dependencies (other than `socket.io-client`). Fully framework-agnostic core logic.
+- **Auto-Enriched Context:** Automatically attaches `PageUrl`, `PageTitle`, `Project`, and `CreatedDate` to every single event payload.
+- **SSR Safe:** Fully compatible with Next.js and Remix.
+
+---
+
+## 🚀 Getting Started
+
+### 1. Install
+
+```bash
+yarn add nova-hooks
+```
+
+```bash
+npm i nova-hooks
+```
+
+### 2. Initialization
+
+> [!IMPORTANT]
+> Ensure the socket connection is established at the root of your application using the `connectSocket` method.
+
+```tsx
+import { connectSocket } from "nova-hooks";
+import { useEffect } from "react";
+
+const App = () => {
+  useEffect(() => {
+    connectSocket(import.meta.env.VITE_APP_SOCKET, "WolfPack");
+  }, []);
+
+  // app code...
+};
+```
+
+---
+
+## 🛠️ Usage Examples
+
+### 1. Zero-Config Global Click Tracking
+
+Place `useGlobalClickTracker` in your authenticated layout. It will automatically listen to the DOM and seamlessly track clicks on any `<button>`, `<a>`, or `cursor: pointer` element!
+
+```tsx
+import { useGlobalClickTracker } from "nova-hooks";
+
+const ProtectedLayout = ({ children }) => {
+  const { user } = useAuth();
+
+  // Magic happens here! Tracks all UI clicks across the entire app.
+  useGlobalClickTracker(user?.empId, user?.roleId);
+
+  return <>{children}</>;
+};
+```
+
+_Note: It will intelligently extract labels from `innerText`, `title`, `aria-label`, or auto-generate a fallback CSS Path!_
+
+### 2. Explicit Tracking (Optional Overrides)
+
+If you want to override the auto-detected name for a specific button, just attach the `data-nova-*` attributes:
+
+```tsx
+<button
+  data-nova-track-id="Custom Task Action"
+  data-nova-track-type={ActionType.Button}
+>
+  Track Me Specifically
+</button>
+```
+
+### 3. Accurate Page Dwell Time
+
+Track exactly how long a user actively stares at a specific page/component. The timer pauses if they switch tabs or minimize the browser!
+
+```tsx
+import { usePageTimeTracker } from "nova-hooks";
+
+export const Dashboard = () => {
+  const { user } = useAuth();
+
+  // Tracks active dwell time and emits it automatically when the user leaves the page
+  usePageTimeTracker("Home Dashboard", user?.empId, user?.roleId);
+
+  return <div>Welcome to the Dashboard</div>;
+};
+```
+
+### 4. Manual / Imperative Tracking
+
+If you need to track events programmatically (like inside an API success callback), use the `withEvent` method:
+
+```tsx
+import { withEvent, ActionType } from "nova-hooks";
+
+const doLogin = () => {
+  api.login().then(() => {
+    withEvent({
+      Action: "Login Success",
+      ActionType: ActionType.Login,
+      EmpId: "EMP-123",
+      EmpRole: "Admin",
+      Count: 1,
+    });
+  });
+};
+```
+
+---
+
+## 📦 Exports & Types
+
+| Name                    | Type                                                         | Description                                                             |
+| ----------------------- | ------------------------------------------------------------ | ----------------------------------------------------------------------- |
+| `ActionType`            | `object`                                                     | Predefined enum-like values: `"Button"`, `"Menu"`, `"Login"`, `"Link"`  |
+| `PageVisitAction`       | `string`                                                     | Constant string `"Page Visit"` used for tracking page visits            |
+| `connectSocket`         | `(socketUrl: string, project: string) => void`               | Connects to the socket server and sets the project name.                |
+| `disconnectSocket`      | `() => void`                                                 | Disconnects and cleans up the active socket connection.                 |
+| `withEvent`             | `(eventData: EventData, callback?: Function) => void`        | Emits a structured event optionally after running a callback.           |
+| `useGlobalClickTracker` | `(empId?: string, roleId?: string) => void`                  | React hook to automatically track global click events.                  |
+| `usePageTimeTracker`    | `(action: string; empId?: string; empRole?: string) => void` | React hook to track active time spent on a page via the Visibility API. |
+
+### EventData Structure
+
+All events are automatically enriched with `Project`, `PageUrl`, `PageTitle`, and an ISO `CreatedDate`.
+
+| Property     | Type                                                              | Description                                                     |
+| ------------ | ----------------------------------------------------------------- | --------------------------------------------------------------- |
+| `ActionType` | `keyof typeof ActionType` \| `typeof PageVisitAction`             | Type of the action.                                             |
+| `Action`     | `string`                                                          | Specific action performed (extracted from DOM or manually set). |
+| `EmpId`      | `string`                                                          | Unique identifier of the employee.                              |
+| `EmpRole`    | `string`                                                          | Role of the employee performing the action.                     |
+| `Count`      | `number` _(only when `ActionType` is from `ActionType`)_          | Number of rapid occurrences of the action (batched).            |
+| `Duration`   | `number` _(seconds, only when `ActionType` is `PageVisitAction`)_ | Duration of the _active_ visit in seconds.                      |