@alexcarpenter/scroll-lock 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Change Log
+
+This project adheres to [Semantic Versioning](http://semver.org/).
+
+## 0.1.0
+
+### Added
+
+- Add `scrollLock(surface?)`, returning an idempotent release function.

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright 2026 Alex Carpenter
+
+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/README.md

@@ -0,0 +1,113 @@
+# Scroll Lock
+
+A tiny scroll lock for dialogs, drawers, popovers, and other overlays.
+
+- **Small.** Less than 1 kB minified and Brotli-compressed.
+- **Fast.** Does not scan descendants or read computed styles.
+- **Focused.** One function and no runtime dependencies.
+- **Composable.** Supports nested overlays and one allowed scroll surface.
+- **Framework-free.** Works directly with React, Vue, Svelte, and vanilla DOM.
+
+```js
+import { scrollLock } from '@alexcarpenter/scroll-lock'
+
+const release = scrollLock()
+release()
+```
+
+## Install
+
+```sh
+npm install @alexcarpenter/scroll-lock
+```
+
+## Usage
+
+Call `scrollLock()` when an overlay opens. It returns an idempotent function
+that restores the page.
+
+```js
+import { scrollLock } from '@alexcarpenter/scroll-lock'
+
+const release = scrollLock()
+
+// Close the overlay later.
+release()
+```
+
+Pass an element to keep that surface interactive and scrollable:
+
+```js
+const release = scrollLock(dialog)
+```
+
+Only the most recent lock is active. Releasing it resumes the previous lock,
+which makes nested dialogs and popovers work naturally.
+
+## React
+
+The returned function is compatible with `useEffect` cleanup, so React support
+does not require an adapter or React dependency.
+
+```tsx
+import { useEffect, useRef } from 'react'
+import { scrollLock } from '@alexcarpenter/scroll-lock'
+
+export function Dialog({ open, children }) {
+  const dialogRef = useRef<HTMLDialogElement>(null)
+
+  useEffect(() => {
+    if (!open) return
+    return scrollLock(dialogRef.current)
+  }, [open])
+
+  return (
+    <dialog ref={dialogRef} open={open}>
+      {children}
+    </dialog>
+  )
+}
+```
+
+For a page-wide lock, omit the reference:
+
+```js
+useEffect(() => {
+  if (open) return scrollLock()
+}, [open])
+```
+
+This also behaves correctly under React Strict Mode because every release
+function is safe to call more than once.
+
+## API
+
+### `scrollLock(surface?)`
+
+Freezes page movement and returns a release function.
+
+- `surface?: HTMLElement | null` — element that remains interactive and
+  scrollable.
+- Returns `() => void` — restores the previous lock or the original page.
+
+## Behavior
+
+- Preserves page coordinates and existing inline styles.
+- Blocks wheel and scroll-key input outside the allowed surface.
+- Contains wheel movement at the allowed surface boundary.
+- Preserves pinch-to-zoom while restricting single-finger page movement.
+- Prevents dragged scrollbars behind an overlay from moving.
+- Rebuilds active listeners after orientation changes.
+- Discards sessions whose allowed surface leaves the document.
+- Creates one temporary stylesheet and listener lifecycle for the active lock.
+
+## Size
+
+The package uses [Size Limit](https://github.com/ai/size-limit) with a hard
+1 kB budget:
+
+```sh
+pnpm test:size
+```
+
+Current size: **964 B** minified and Brotli-compressed.

package/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Lock page scrolling and optionally leave one element scrollable.
+ *
+ * @param node Element to keep interactive and scrollable.
+ * @returns An idempotent function that releases this lock.
+ */
+export function scrollLock(surface?: HTMLElement | null): () => void

package/index.js

@@ -0,0 +1,186 @@
+/** @typedef {[HTMLElement | null, () => void, () => void]} Session */
+
+const anchors = new WeakMap()
+const touchActions = [
+  'pinch-zoom',
+  'pan-x pinch-zoom',
+  'pan-y pinch-zoom',
+  'auto'
+]
+const scrollKey = /^(Space|Page(Up|Down)|End|Home|Arrow(Left|Up|Right|Down))$/
+
+/** @param {HTMLElement} element */
+const pin = element => {
+  const anchor = anchors.get(element)
+  element.scrollLeft = anchor[0]
+  element.scrollTop = anchor[1]
+  anchor[2] = requestAnimationFrame(() => pin(element))
+}
+
+/** @type {Session[]} */
+let stack = []
+let sheet
+let viewport
+
+const prune = () => {
+  for (let i = stack.length; i--; ) {
+    const session = stack[i]
+    if (session[0] && !document.body.contains(session[0])) {
+      session[2]()
+      stack.splice(i, 1)
+    }
+  }
+}
+
+/**
+ * Lock page scrolling and optionally leave one element scrollable.
+ * @param {HTMLElement | null} [surface]
+ * @returns {() => void}
+ */
+export function scrollLock(surface = null) {
+  if (!stack.length) {
+    viewport = [
+      document.body.style.position,
+      document.body.style.inset,
+      document.body.style.overflowY,
+      document.documentElement.style.scrollbarGutter,
+      window.scrollX,
+      window.scrollY
+    ]
+    document.documentElement.style.scrollbarGutter = 'stable'
+    document.body.style.overflowY = 'hidden'
+    document.body.style.position = 'fixed'
+    document.body.style.inset = `-${viewport[5]}px 0 0 -${viewport[4]}px`
+  }
+
+  stack.at(-1)?.[2]()
+  prune()
+
+  let events
+  let marker
+  let blocked = true
+
+  /** @param {WheelEvent} event */
+  const guardWheel = event => {
+    if (!surface || blocked) return event.preventDefault()
+    const distance = surface.scrollHeight - surface.offsetHeight
+    const target = event.target
+    if (
+      distance > 0 &&
+      target !== surface &&
+      target instanceof Node &&
+      surface.contains(target)
+    ) {
+      return
+    }
+    ;(target === surface ||
+      (event.deltaY > 0 && surface.scrollTop >= distance) ||
+      (event.deltaY < 0 && surface.scrollTop <= 0)) &&
+      event.preventDefault()
+  }
+
+  /** @param {KeyboardEvent} event */
+  const guardKey = event => {
+    blocked && scrollKey.test(event.key) && event.preventDefault()
+  }
+
+  /** @param {MouseEvent} event */
+  const hold = event => {
+    const target = event.target
+    if (!(target instanceof HTMLElement) || target === surface) return
+    const anchor = [target.scrollLeft, target.scrollTop]
+    anchors.set(target, anchor)
+    pin(target)
+  }
+
+  /** @param {MouseEvent} event */
+  const release = event => {
+    const target = event.target
+    if (!(target instanceof HTMLElement)) return
+    const anchor = anchors.get(target)
+    if (anchor) {
+      requestAnimationFrame(() => {
+        cancelAnimationFrame(anchor[2])
+        anchors.delete(target)
+      })
+    }
+  }
+
+  const mount = () => {
+    if (events) return
+    blocked = true
+    events = new AbortController()
+    const options = {
+      capture: true,
+      passive: false,
+      signal: events.signal
+    }
+    window.addEventListener('wheel', guardWheel, options)
+    window.addEventListener('keydown', guardKey, options)
+    window.addEventListener('mousedown', hold, options)
+    window.addEventListener('mouseup', release, options)
+
+    sheet ||= document.head.appendChild(document.createElement('style'))
+    const base = '*{pointer-events:none}*,::backdrop{touch-action:none}'
+
+    if (surface) {
+      marker = `n${stack.length}`
+      surface.classList.add(marker)
+      const x = surface.scrollWidth > surface.clientWidth
+      const y = surface.scrollHeight > surface.clientHeight
+      const touch = touchActions[+x + 2 * +y]
+      sheet.textContent = `${base}.${marker},.${marker} *{pointer-events:auto;overscroll-behavior:contain;touch-action:${touch}}`
+      surface.addEventListener('mouseover', () => (blocked = false), options)
+      surface.addEventListener('mouseout', () => (blocked = true), options)
+    } else {
+      sheet.textContent = base
+    }
+  }
+
+  const unmount = () => {
+    if (!events) return
+    events = events.abort()
+    marker && surface.classList.remove(marker)
+  }
+
+  /** @type {Session} */
+  const session = [surface, mount, unmount]
+
+  if (!surface || document.body.contains(surface)) {
+    stack.push(session)
+    mount()
+  }
+
+  const orientation = window.matchMedia('(orientation:portrait)')
+  orientation.onchange = () => {
+    if (events) {
+      unmount()
+      mount()
+    }
+  }
+
+  let released
+  return () => {
+    if (released) return
+    released = true
+    orientation.onchange = null
+    const index = stack.indexOf(session)
+    if (~index) {
+      const top = index === stack.length - 1
+      unmount()
+      stack.splice(index, 1)
+      prune()
+      top && stack.at(-1)?.[1]()
+    }
+    if (!stack.length) {
+      sheet = sheet?.remove()
+      document.body.style.position = viewport[0]
+      document.body.style.inset = viewport[1]
+      document.body.style.overflowY = viewport[2]
+      window.scroll(viewport[4], viewport[5])
+      requestAnimationFrame(() => {
+        document.documentElement.style.scrollbarGutter = viewport[3]
+      })
+    }
+  }
+}

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@alexcarpenter/scroll-lock",
+  "version": "0.1.0",
+  "description": "Sub-kilobyte scroll locking for overlays",
+  "keywords": [
+    "scroll",
+    "lock",
+    "scrollbar",
+    "modal",
+    "dialog"
+  ],
+  "license": "MIT",
+  "author": "Alex Carpenter",
+  "repository": "alexcarpenter/scroll-lock",
+  "funding": [
+    {
+      "type": "github",
+      "url": "https://github.com/sponsors/alexcarpenter"
+    }
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "types": "./index.d.ts",
+  "exports": {
+    ".": "./index.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "test:lint": "oxlint",
+    "test:coverage": "vitest run --coverage",
+    "test:types": "check-dts",
+    "test:size": "size-limit",
+    "test": "pnpm run /^test:/"
+  },
+  "devDependencies": {
+    "@logux/oxc-configs": "^0.2.0",
+    "@size-limit/preset-small-lib": "^12.0.1",
+    "@vitest/browser": "^4.0.16",
+    "@vitest/browser-playwright": "^4.0.16",
+    "@vitest/coverage-v8": "^4.0.16",
+    "actions-up": "^1.12.0",
+    "check-dts": "^1.0.0",
+    "multiocular": "^0.8.2",
+    "oxfmt": "^0.42.0",
+    "oxlint": "1.58.0",
+    "oxlint-tsgolint": "0.18.1",
+    "playwright": "^1.57.0",
+    "size-limit": "^12.0.1",
+    "typescript": "^6.0.2",
+    "vitest": "^4.0.16"
+  },
+  "size-limit": [
+    {
+      "import": "{ scrollLock }",
+      "limit": "1 kB"
+    }
+  ],
+  "engines": {
+    "node": "^22.0.0 || >=24.0.0"
+  }
+}