npm package: @rfkhusnutdinov/scroll-lock-manager
Description: A lightweight JavaScript utility to manage body scroll without layout shifts.
Author: Rinat Khusnutdinov
Latest version: 1.0.1

# ScrollLockManager

A lightweight JavaScript utility to manage body scroll without layout shifts.
**Automatically detects when scroll is locked, even by other scripts or libraries, and applies compensation to prevent content jumps.**

## Features

- Automatically detects when body scroll is locked, even by other code or libraries
- Automatically compensates scrollbar width with `margin-right` to prevent content jumps
- Overrides any existing `margin-right` set by other libraries for consistent behavior
- Supports native `scrollbar-gutter` when available
- Observes `body` overflow changes using [OverflowObserver](https://github.com/rfkhusnutdinov/overflow-observer)
- Tracks scrollbar width with [ScrollbarWidthObserver](https://github.com/rfkhusnutdinov/scrollbar-width-observer)
- Lock and unlock scroll programmatically
- Singleton pattern ensures only one instance

## Installation

### Install from npm

```bash
npm install @rfkhusnutdinov/scroll-lock-manager
```

```javascript
import ScrollLockManager from "@rfkhusnutdinov/scroll-lock-manager";
```

### Use ScrollLockManager from CDN

```html
<script src="https://cdn.jsdelivr.net/npm/@rfkhusnutdinov/scroll-lock-manager@latest"></script>
```

## Usage

```javascript
const scrollManager = new ScrollLockManager({
  useScrollbarGutter: true, // optional, default is true
});

// Lock scroll
scrollManager.lockScroll();

// Unlock scroll
scrollManager.unlockScroll();

// Disconnect and clean up
scrollManager.disconnect();
```

### Notes

- ScrollLockManager prevents document jumps that usually occur when `overflow: hidden` is applied by compensating the scrollbar width with `margin-right`.
- The plugin automatically detects when scroll is locked, even if done by other scripts or libraries, and applies the necessary styles to maintain consistent layout.
- Any existing `margin-right` set by other libraries is overridden to ensure correct alignment and prevent layout shifts.
- The `useScrollbarGutter` option enables the native CSS `scrollbar-gutter` property if supported by the browser, providing smoother layouts.
- CSS classes are applied automatically: `scroll-lock-manager-overflow-hidden` is added when body overflow is hidden.
- Singleton pattern ensures only one instance of ScrollLockManager is active at a time.

## API

| Method                                        | Description                                              |
| --------------------------------------------- | -------------------------------------------------------- |
| new ScrollLockManager({ useScrollbarGutter }) | Initializes the manager or returns the existing instance |
| lockScroll()                                  | Locks body scroll                                        |
| unlockScroll()                                | Unlocks body scroll                                      |
| disconnect()                                  | Stops observing and cleans up styles/observers           |