scroll-tracking-walkeros/README.md

Custom scroll tracking used as an additional source for WalkerOS.

# scroll-tracking-walkeros

A lightweight, ready-to-use WalkerOS utility for tracking how far a user has scrolled through an article or page.  
Includes both a **stateless reporting function** (`scrollReport`) and an **auto-tracking helper** (`initScrollTracking`) that attaches scroll listeners for you.
Supports both *CommonJS* and *ES Modules*.

---

## 📦 Installation

```bash
npm install scroll-tracking-walkeros
# or
yarn add scroll-tracking-walkeros
```

---

## 🚀 Usage

### 1. `scrollReport()`

Returns the **current scroll percentage** and **maximum scroll percentage reached so far**.

By default, it tries to measure scroll depth against an element with the ID `articlebody`.  
If that element is missing, it will fall back to the full `document.body`.

#### Example
```ts
import { scrollReport } from "scroll-tracking-walkeros";

const { scrollPercent, scrollMaximum } = scrollReport();
console.log(`Current: ${scrollPercent}, Max: ${scrollMaximum}`);
```

#### Returns
| Property        | Type     | Description |
|-----------------|----------|-------------|
| `scrollPercent` | `number` | Current scroll position (0–1) relative to the content height. |
| `scrollMaximum` | `number` | Maximum scroll percentage reached so far (0–1). |

#### ⚠️ Important
For accurate tracking, **wrap your main scrollable content** in an element with:

```html
<div id="articlebody">
  <!-- Your content -->
</div>
```

---

### 2. `initScrollTracking(callback)`

Attaches a `scroll` event listener and **automatically calls your callback** whenever the scroll percentage changes.  
Also tracks the **previous scroll percentage** internally.

#### Example (React)
```ts
import { initScrollTracking } from "scroll-tracking-walkeros";

useEffect(() => {
  const cleanup = initScrollTracking(({ scrollPercent, scrollMaximum, previousPercent }) => {
    console.log("Scrolled:", scrollPercent, "Max:", scrollMaximum, "Previous:", previousPercent);
  });

  return cleanup; // Remove listener on unmount
}, []);
```

#### Callback Parameters
| Property           | Type       | Description |
|--------------------|------------|-------------|
| `scrollPercent`    | `number`   | Current scroll position (0–1). |
| `scrollMaximum`    | `number`   | Maximum scroll percentage reached so far (0–1). |
| `previousPercent`  | `number?`  | The scroll percentage from the last callback execution, or `null` on first run. |

#### Returns
`initScrollTracking` returns a **cleanup function** to remove the scroll listener.

---

## 📄 API Reference

### `scrollReport()`
- **Type:** `() => { scrollPercent: number; scrollMaximum: number }`
- Calculates and returns the current scroll metrics.

### `initScrollTracking(callback)`
- **Type:** `(callback: ({ scrollPercent, scrollMaximum, previousPercent }) => void) => () => void`
- Starts automatic scroll tracking and calls your callback when values change.
- Returns a cleanup function.

---

## 🛠 Development Notes
- Designed for **WalkerOS** integrations but works in any browser environment.
- No dependencies — pure JavaScript.
- Uses `window.scrollY` and element height calculations.

---

## 📜 License
MIT - Developed by [sleepycat666](https://github.com/sleepycat666) for [Public Value Technologies GmbH](https://pub.tech/)