@develemit/web-hooks 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.2.0 - 2026-11-05
+
+- `unsaved-guard`: `useUnsavedChangesGuard(dirty)` and the pure `handleBeforeUnload`. Attached only while dirty and sets `returnValue = ''` as well as `preventDefault()`, which older Safari and Chrome need. `beforeunload` only; in-app navigation stays in the app.
+- `hotkey`: `useHotkey('mod+k', fn, { enabled, allowInInputs, preventDefault })` and the pure `parseHotkey`, `matchHotkey`, `detectApple`. Ignores case and Caps Lock, `mod` is Cmd on Apple and Ctrl elsewhere, exact modifier match, text fields skipped by default.
+- `auto-grow`: `useAutoGrowTextarea(ref, value, { maxHeight })` and the pure `nextHeight`. Re-measures on value change and on `visualViewport` resize (keyboard), with a `window` fallback; `overflowY: auto` only when capped.
+- `debounce`: `useDebouncedValue(value, ms)`, `useDebouncedCallback(fn, ms)` (returns a stable function with `cancel` and `flush`, cancels on unmount, always calls the latest `fn`) and the pure `createDebouncer`.
+- `storage-state`: `useStorageState(key, defaultValue, { storage, serialize, parse })` returning `[value, set, remove]`. Built on `useSyncExternalStore`, so the first client render matches the server (the default) with no hydration mismatch; stays in sync across hooks and tabs; bad JSON gives the default; a refused `setItem` (quota, Safari private mode) is kept in memory so the UI still updates.
+- `visibility-polling`: `useVisibilityPolling(fn, intervalMs, { enabled, immediate, jitter, runOnVisible })` and the pure `nextDelay`. Chained timeouts so a slow run never overlaps, paused while the page is hidden (a locked phone makes no calls), one run on becoming visible, and the listener is always removed on unmount.
+- `outside-press`: `useOutsidePress(refs, onOutsidePress, { enabled })` and the pure `isOutside`. Listens to `pointerdown` in the capture phase so taps on non-clickable elements close menus on iPhone, only while enabled, with the trigger and portalled panels as inside refs.
+- `media-query`: `useMediaQuery(query, { serverDefault })`, `useReducedMotion` and `useCoarsePointer`. Correct on the first client render, no hydration mismatch, safe without `matchMedia`, and one shared `MediaQueryList` per query.
+- `scroll-lock`: `useScrollLock` and `lockScroll()` / `unlockScroll()`. Counted locks, `position: fixed` so iOS Safari and standalone PWAs stop scrolling the background, exact restore of previous inline styles and scroll position, scrollbar-width padding on desktop.
+- `clipboard`: the `execCommand` fallback now puts focus back on the element that had it (and never scrolls to the temporary textarea). It used to leave `<body>` focused after a copy on plain-http PWAs.
+- `focus-trap`: under StrictMode the captured opener was dropped by the simulated effect cleanup, so closing a trap (e.g. a dialog stacked in an open nav) left focus on `<body>`. The opener is now cleared when the trap deactivates.
+- `escape`: `useEscape` ignores Escape pressed during IME composition (`isComposing` or `keyCode` 229), so cancelling a composition no longer closes the menu.
+- The root `@develemit/web-hooks` entry now carries the `"use client"` banner like the subpath entries, so a server component importing from the root fails loudly in Next.
+
 ## 0.1.0
 
 - `drawer-swipe`: `useDrawerSwipe` and the pure `resolveSwipeIntent`. Swipe right from mid-screen opens a mobile nav drawer, left closes it. The left 60px band is left to the browser's back gesture.

package/README.md

@@ -9,6 +9,15 @@ that every app ends up hand-copying from the last one.
 | `@develemit/web-hooks/focus-trap` | Keep Tab focus inside an open dialog or drawer, restore it on close |
 | `@develemit/web-hooks/escape` | Run a callback when Escape is pressed |
 | `@develemit/web-hooks/clipboard` | Copy text, with the fallback that works on plain-http PWAs |
+| `@develemit/web-hooks/scroll-lock` | Lock page scroll behind a modal or drawer, counted, and it works on iOS |
+| `@develemit/web-hooks/media-query` | Track a media query, reduced motion or a coarse pointer, with no hydration mismatch |
+| `@develemit/web-hooks/outside-press` | Close a menu or popover on a press outside it, including taps on iPhone |
+| `@develemit/web-hooks/visibility-polling` | Poll on an interval that pauses while the page is hidden |
+| `@develemit/web-hooks/debounce` | Debounce a value or a callback |
+| `@develemit/web-hooks/storage-state` | State persisted to localStorage or sessionStorage, SSR-safe and synced across tabs |
+| `@develemit/web-hooks/unsaved-guard` | Warn before the tab closes while a form is dirty |
+| `@develemit/web-hooks/hotkey` | Keyboard shortcuts such as `mod+k` |
+| `@develemit/web-hooks/auto-grow` | Grow a textarea with its content, keyboard-aware |
 
 Behavior only. No styling and no components: each app keeps its own look.
 
@@ -74,6 +83,115 @@ const { copy, status } = useCopyFeedback({ resetMs: 1500 });
 rejects. On plain-http origins (a PWA over a Tailscale address)
 `navigator.clipboard` doesn't exist, so it falls back to `execCommand('copy')`.
 
+### Lock page scroll behind an overlay
+
+```tsx
+import { useScrollLock } from '@develemit/web-hooks/scroll-lock';
+
+useScrollLock(open);
+```
+
+Uses `position: fixed` on `body` because iOS Safari ignores `overflow: hidden`
+for touch scrolling. Locks are counted, so a lightbox closing inside an open
+drawer leaves the page locked. When the last lock releases, the exact previous
+inline styles and the scroll position come back. `lockScroll()` returns a
+release function (safe to call twice) for use outside React.
+
+### Match a media query
+
+```tsx
+import { useMediaQuery, useReducedMotion, useCoarsePointer } from '@develemit/web-hooks/media-query';
+
+const narrow = useMediaQuery('(max-width: 767px)', { serverDefault: false });
+const reduce = useReducedMotion();
+const touch = useCoarsePointer();
+```
+
+Built on `useSyncExternalStore`, so the first client render already has the
+real value (no desktop frame on a phone). The server render and hydration use
+`serverDefault` (default `false`); React then re-renders with the real value
+without a mismatch warning. There are no built-in breakpoints: pass your own
+query. Where `matchMedia` is missing (jsdom tests) the hook returns
+`serverDefault` instead of throwing. Hooks with the same query share one
+`MediaQueryList`, and Safari before 14 is supported through `addListener`.
+
+### Close on an outside press
+
+```tsx
+import { useOutsidePress } from '@develemit/web-hooks/outside-press';
+import { useEscape } from '@develemit/web-hooks/escape';
+
+const menu = useRef<HTMLDivElement>(null);
+const trigger = useRef<HTMLButtonElement>(null);
+useOutsidePress([menu, trigger], () => setOpen(false), { enabled: open });
+useEscape(() => setOpen(false), open);
+```
+
+Listens to `pointerdown` on `document` in the capture phase, only while
+`enabled`. `mousedown` never fires on iOS for a tap on a non-clickable element,
+so copies built on it leave the menu open. Pass the trigger as well as the
+panel, or tapping the trigger closes and instantly reopens the menu. Pass a
+portalled panel's ref too. Right clicks are ignored, and a target removed from
+the DOM during the event counts as inside. The callback is read through a ref,
+so it needs no `useCallback`.
+
+### visibility-polling
+
+```tsx
+import { useVisibilityPolling } from '@develemit/web-hooks/visibility-polling';
+
+useVisibilityPolling(() => refresh(), 5000, { jitter: 0.2 });
+```
+
+Runs `fn` every `intervalMs` only while the page is visible. When the tab is
+hidden (a locked phone) the timer is cleared; when it is visible again `fn`
+runs once right away and the schedule resumes. The next run is scheduled after
+the previous one finishes, so a slow promise never overlaps. Options:
+`enabled` (default true), `immediate` (run on mount, default true), `jitter`
+(0–1 fraction of the interval added at random, default 0) and `runOnVisible`
+(default true). `fn` is read through a ref. A throw or rejection doesn't stop
+the schedule; handle errors inside `fn`. It decides when to run, not caching
+or dedupe.
+
+### debounce
+
+```tsx
+import { useDebouncedValue, useDebouncedCallback } from '@develemit/web-hooks/debounce';
+
+const debouncedSearch = useDebouncedValue(search, 300);
+
+const run = useDebouncedCallback((q: string) => fetchResults(q), 300);
+run('inv'); // later calls reset the timer; only the last runs
+run.cancel(); // drop the pending call
+run.flush(); // run it now
+```
+
+`useDebouncedValue` returns the value once it has stopped changing for `ms`.
+`useDebouncedCallback` returns one function for the life of the component; it
+always calls the latest `fn` and `ms`, so it needs no `useCallback`, and a
+pending call is cancelled on unmount.
+
+### storage-state
+
+```tsx
+import { useStorageState } from '@develemit/web-hooks/storage-state';
+
+const [recent, setRecent, clearRecent] = useStorageState<string[]>('recent', []);
+setRecent((prev) => ['pnpm dev', ...prev]);
+const [draft, setDraft] = useStorageState('draft', '', { storage: 'session' });
+```
+
+The server and the first client render both return `defaultValue`; the stored
+value arrives right after hydration, so there is no mismatch. Hooks with the
+same key stay in sync in this tab, and other tabs through the `storage` event.
+The setter takes a value or an updater. Options: `storage` (`'local'` default,
+or `'session'`), `serialize` and `parse` (JSON by default; a `parse` that
+throws gives `defaultValue`, so legacy non-JSON values and validators both
+work). A refused `setItem` (full quota, Safari private mode) never throws: the
+new value is kept in memory for the rest of the page's life and the UI
+updates. Keep `defaultValue` stable (a constant or a primitive); it is read
+again only when the stored value or key changes.
+
 ### Migrating from the per-app copies
 
 | App | Old | New |
@@ -82,3 +200,51 @@ rejects. On plain-http origins (a PWA over a Tailscale address)
 | emit-social | `useFocusTrap(ref, { active, returnFocusRef })` plus `useEscape(fn, active)` | Same signatures. |
 | develemit-commerce | `const onKeyDown = useFocusTrap(ref, active, onEscape)` | `useFocusTrap(ref, { active })` and `useEscape(onEscape, active)`. Drop the returned `onKeyDown` handler. |
 | centraflow | `const ref = useFocusTrap(active)` | `const ref = useRef<HTMLElement>(null)`, then `useFocusTrap(ref, { active })`. |
+
+### unsaved-guard
+
+```tsx
+import { useUnsavedChangesGuard } from '@develemit/web-hooks/unsaved-guard';
+
+useUnsavedChangesGuard(isDirty);
+```
+
+While `dirty` is true the browser asks before the tab closes or reloads. It
+sets both `preventDefault()` and `returnValue = ''`, because older Safari and
+Chrome ignore `preventDefault()` alone. This covers `beforeunload` only:
+Next's App Router has no stable way to block in-app navigation, so that stays
+in the app.
+
+### hotkey
+
+```tsx
+import { useHotkey, matchHotkey } from '@develemit/web-hooks/hotkey';
+
+useHotkey('mod+k', () => setOpen((o) => !o));
+useHotkey('mod+k', toggle, { allowInInputs: true, preventDefault: false });
+```
+
+Combos are modifiers (`mod`, `ctrl`, `meta`, `alt`, `shift`) then one key:
+`mod+k`, `shift+/`, `escape`. `mod` is Cmd on Apple devices (iPad in desktop
+mode included) and Ctrl elsewhere. Case and Caps Lock don't matter, and the
+modifier set must match exactly. Text fields (`input`, `textarea`, `select`,
+contenteditable) are skipped unless `allowInInputs`. Options: `enabled`
+(default true), `allowInInputs` (false), `preventDefault` (true). `matchHotkey(event,
+combo, isApple)` is the pure matcher; `detectApple(navigator)` supplies
+`isApple`. No key sequences.
+
+### auto-grow
+
+```tsx
+import { useAutoGrowTextarea } from '@develemit/web-hooks/auto-grow';
+
+const ref = useRef<HTMLTextAreaElement>(null);
+useAutoGrowTextarea(ref, value, { maxHeight: 240 });
+```
+
+Resizes the textarea to fit its content on every `value` change and whenever
+the visual viewport resizes (the iPhone keyboard opening or closing), falling
+back to `window` `resize`. At `maxHeight` it stops growing and sets
+`overflowY: auto`. The pure `nextHeight(scrollHeight, maxHeight)` does the
+clamping.
+

package/dist/auto-grow.cjs

@@ -0,0 +1,60 @@
+"use client";
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/auto-grow/index.ts
+var auto_grow_exports = {};
+__export(auto_grow_exports, {
+  nextHeight: () => nextHeight,
+  useAutoGrowTextarea: () => useAutoGrowTextarea
+});
+module.exports = __toCommonJS(auto_grow_exports);
+
+// src/auto-grow/next-height.ts
+function nextHeight(scrollHeight, maxHeight) {
+  const content = Math.ceil(scrollHeight);
+  if (maxHeight !== void 0 && content > maxHeight) return { height: maxHeight, capped: true };
+  return { height: content, capped: false };
+}
+
+// src/auto-grow/use-auto-grow-textarea.ts
+var import_react = require("react");
+var useIsomorphicLayoutEffect = typeof window === "undefined" ? import_react.useEffect : import_react.useLayoutEffect;
+function useAutoGrowTextarea(ref, value, { maxHeight } = {}) {
+  const resize = (0, import_react.useCallback)(() => {
+    const el = ref.current;
+    if (!el) return;
+    el.style.height = "auto";
+    const { height, capped } = nextHeight(el.scrollHeight, maxHeight);
+    el.style.height = `${height}px`;
+    el.style.overflowY = capped ? "auto" : "hidden";
+  }, [ref, maxHeight]);
+  useIsomorphicLayoutEffect(resize, [resize, value]);
+  (0, import_react.useEffect)(() => {
+    const viewport = window.visualViewport;
+    const target = viewport ?? window;
+    target.addEventListener("resize", resize);
+    return () => target.removeEventListener("resize", resize);
+  }, [resize]);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  nextHeight,
+  useAutoGrowTextarea
+});

package/dist/auto-grow.d.cts

@@ -0,0 +1,14 @@
+import { RefObject } from 'react';
+
+interface NextHeight {
+    height: number;
+    capped: boolean;
+}
+declare function nextHeight(scrollHeight: number, maxHeight?: number): NextHeight;
+
+interface UseAutoGrowTextareaOptions {
+    maxHeight?: number;
+}
+declare function useAutoGrowTextarea(ref: RefObject<HTMLTextAreaElement | null>, value: string, { maxHeight }?: UseAutoGrowTextareaOptions): void;
+
+export { type NextHeight, type UseAutoGrowTextareaOptions, nextHeight, useAutoGrowTextarea };

package/dist/auto-grow.d.ts

@@ -0,0 +1,14 @@
+import { RefObject } from 'react';
+
+interface NextHeight {
+    height: number;
+    capped: boolean;
+}
+declare function nextHeight(scrollHeight: number, maxHeight?: number): NextHeight;
+
+interface UseAutoGrowTextareaOptions {
+    maxHeight?: number;
+}
+declare function useAutoGrowTextarea(ref: RefObject<HTMLTextAreaElement | null>, value: string, { maxHeight }?: UseAutoGrowTextareaOptions): void;
+
+export { type NextHeight, type UseAutoGrowTextareaOptions, nextHeight, useAutoGrowTextarea };

package/dist/auto-grow.js

@@ -0,0 +1,9 @@
+"use client";
+import {
+  nextHeight,
+  useAutoGrowTextarea
+} from "./chunk-5CA5RIMH.js";
+export {
+  nextHeight,
+  useAutoGrowTextarea
+};

package/dist/chunk-3CACI4OQ.js

@@ -0,0 +1,68 @@
+"use client";
+
+// src/clipboard/copy-text.ts
+async function copyText(text) {
+  const hasClipboardApi = typeof navigator !== "undefined" && !!navigator.clipboard?.writeText && typeof window !== "undefined" && window.isSecureContext;
+  if (hasClipboardApi) {
+    try {
+      await navigator.clipboard.writeText(text);
+      return { ok: true };
+    } catch {
+    }
+  }
+  if (execCommandCopy(text)) return { ok: true };
+  return { ok: false, reason: hasClipboardApi ? "denied" : "unavailable" };
+}
+function execCommandCopy(text) {
+  if (typeof document === "undefined") return false;
+  const textarea = document.createElement("textarea");
+  textarea.value = text;
+  textarea.readOnly = true;
+  textarea.style.position = "fixed";
+  textarea.style.top = "-1000px";
+  textarea.style.left = "-1000px";
+  textarea.style.fontSize = "16px";
+  const previouslyFocused = document.activeElement;
+  document.body.appendChild(textarea);
+  try {
+    textarea.focus({ preventScroll: true });
+    textarea.select();
+    textarea.setSelectionRange(0, text.length);
+    return document.execCommand("copy");
+  } catch {
+    return false;
+  } finally {
+    document.body.removeChild(textarea);
+    if (previouslyFocused instanceof HTMLElement && previouslyFocused !== document.body) {
+      previouslyFocused.focus({ preventScroll: true });
+    }
+  }
+}
+
+// src/clipboard/use-copy-feedback.ts
+import { useCallback, useEffect, useRef, useState } from "react";
+function useCopyFeedback({ resetMs = 1500 } = {}) {
+  const [status, setStatus] = useState("idle");
+  const timerRef = useRef(void 0);
+  const clearTimer = useCallback(() => {
+    if (timerRef.current !== void 0) clearTimeout(timerRef.current);
+    timerRef.current = void 0;
+  }, []);
+  useEffect(() => clearTimer, [clearTimer]);
+  const copy = useCallback(
+    async (text) => {
+      const result = await copyText(text);
+      clearTimer();
+      setStatus(result.ok ? "copied" : "failed");
+      timerRef.current = setTimeout(() => setStatus("idle"), resetMs);
+      return result;
+    },
+    [clearTimer, resetMs]
+  );
+  return { copy, status };
+}
+
+export {
+  copyText,
+  useCopyFeedback
+};

package/dist/chunk-3UGRXQIA.js

@@ -0,0 +1,39 @@
+"use client";
+
+// src/outside-press/outside-press.ts
+function isOutside(target, elements) {
+  if (!target) return false;
+  if (!target.isConnected) return false;
+  return !elements.some((el) => el?.contains(target));
+}
+function isPrimaryPress(event) {
+  return !(event.pointerType === "mouse" && event.button !== 0);
+}
+
+// src/outside-press/use-outside-press.ts
+import { useEffect, useRef } from "react";
+function useOutsidePress(refs, onOutsidePress, { enabled = true } = {}) {
+  const refsRef = useRef(refs);
+  const handlerRef = useRef(onOutsidePress);
+  useEffect(() => {
+    refsRef.current = refs;
+    handlerRef.current = onOutsidePress;
+  });
+  useEffect(() => {
+    if (!enabled) return;
+    function onPointerDown(event) {
+      if (!isPrimaryPress(event)) return;
+      const list = Array.isArray(refsRef.current) ? refsRef.current : [refsRef.current];
+      const elements = list.map((ref) => ref.current);
+      if (isOutside(event.target, elements)) handlerRef.current(event);
+    }
+    document.addEventListener("pointerdown", onPointerDown, true);
+    return () => document.removeEventListener("pointerdown", onPointerDown, true);
+  }, [enabled]);
+}
+
+export {
+  isOutside,
+  isPrimaryPress,
+  useOutsidePress
+};

package/dist/chunk-5CA5RIMH.js

@@ -0,0 +1,34 @@
+"use client";
+
+// src/auto-grow/next-height.ts
+function nextHeight(scrollHeight, maxHeight) {
+  const content = Math.ceil(scrollHeight);
+  if (maxHeight !== void 0 && content > maxHeight) return { height: maxHeight, capped: true };
+  return { height: content, capped: false };
+}
+
+// src/auto-grow/use-auto-grow-textarea.ts
+import { useCallback, useEffect, useLayoutEffect } from "react";
+var useIsomorphicLayoutEffect = typeof window === "undefined" ? useEffect : useLayoutEffect;
+function useAutoGrowTextarea(ref, value, { maxHeight } = {}) {
+  const resize = useCallback(() => {
+    const el = ref.current;
+    if (!el) return;
+    el.style.height = "auto";
+    const { height, capped } = nextHeight(el.scrollHeight, maxHeight);
+    el.style.height = `${height}px`;
+    el.style.overflowY = capped ? "auto" : "hidden";
+  }, [ref, maxHeight]);
+  useIsomorphicLayoutEffect(resize, [resize, value]);
+  useEffect(() => {
+    const viewport = window.visualViewport;
+    const target = viewport ?? window;
+    target.addEventListener("resize", resize);
+    return () => target.removeEventListener("resize", resize);
+  }, [resize]);
+}
+
+export {
+  nextHeight,
+  useAutoGrowTextarea
+};

package/dist/chunk-5KIH2XLV.js

@@ -0,0 +1,136 @@
+"use client";
+
+// src/storage-state/use-storage-state.ts
+import { useCallback, useEffect, useRef, useSyncExternalStore } from "react";
+
+// src/storage-state/storage-store.ts
+function getStorage(kind) {
+  try {
+    if (typeof window === "undefined") return null;
+    return kind === "session" ? window.sessionStorage : window.localStorage;
+  } catch {
+    return null;
+  }
+}
+function readRaw(storage, key) {
+  try {
+    return storage ? storage.getItem(key) : null;
+  } catch {
+    return null;
+  }
+}
+function writeRaw(storage, key, value) {
+  try {
+    if (!storage) return false;
+    storage.setItem(key, value);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function removeRaw(storage, key) {
+  try {
+    if (!storage) return false;
+    storage.removeItem(key);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function parseOr(raw, parse, fallback) {
+  if (raw === null) return fallback;
+  try {
+    return parse(raw);
+  } catch {
+    return fallback;
+  }
+}
+var slot = (kind, key) => `${kind}\0${key}`;
+var memory = /* @__PURE__ */ new Map();
+var listeners = /* @__PURE__ */ new Map();
+function readCurrent(kind, key) {
+  const held = memory.get(slot(kind, key));
+  if (held !== void 0) return held;
+  return readRaw(getStorage(kind), key);
+}
+function notify(id) {
+  for (const listener of [...listeners.get(id) ?? []]) listener();
+}
+function writeCurrent(kind, key, raw) {
+  const id = slot(kind, key);
+  if (writeRaw(getStorage(kind), key, raw)) memory.delete(id);
+  else memory.set(id, raw);
+  notify(id);
+}
+function removeCurrent(kind, key) {
+  const id = slot(kind, key);
+  if (removeRaw(getStorage(kind), key)) memory.delete(id);
+  else memory.set(id, null);
+  notify(id);
+}
+function onStorageEvent(event) {
+  const kinds = [];
+  if (!event.storageArea || event.storageArea === getStorage("local")) kinds.push("local");
+  if (!event.storageArea || event.storageArea === getStorage("session")) kinds.push("session");
+  for (const id of [...listeners.keys()]) {
+    const [kind, key] = id.split("\0");
+    if (!kinds.includes(kind)) continue;
+    if (event.key !== null && event.key !== key) continue;
+    memory.delete(id);
+    notify(id);
+  }
+}
+function subscribeToKey(kind, key, listener) {
+  const id = slot(kind, key);
+  const wasEmpty = listeners.size === 0;
+  let set = listeners.get(id);
+  if (!set) listeners.set(id, set = /* @__PURE__ */ new Set());
+  set.add(listener);
+  if (wasEmpty) window.addEventListener("storage", onStorageEvent);
+  return () => {
+    const current = listeners.get(id);
+    current?.delete(listener);
+    if (current?.size === 0) listeners.delete(id);
+    if (listeners.size === 0) window.removeEventListener("storage", onStorageEvent);
+  };
+}
+
+// src/storage-state/use-storage-state.ts
+function useStorageState(key, defaultValue, options = {}) {
+  const kind = options.storage ?? "local";
+  const serialize = options.serialize ?? JSON.stringify;
+  const parse = options.parse ?? JSON.parse;
+  const latest = useRef({ serialize, parse, defaultValue });
+  useEffect(() => {
+    latest.current = { serialize, parse, defaultValue };
+  });
+  const cache = useRef(null);
+  const subscribe = useCallback((onChange) => subscribeToKey(kind, key, onChange), [kind, key]);
+  const getSnapshot = useCallback(() => {
+    const raw = readCurrent(kind, key);
+    const hit = cache.current;
+    if (hit && hit.kind === kind && hit.key === key && hit.raw === raw && hit.parse === parse) return hit.value;
+    const value2 = parseOr(raw, parse, defaultValue);
+    cache.current = { kind, key, raw, parse, value: value2 };
+    return value2;
+  }, [kind, key, parse, defaultValue]);
+  const getServerSnapshot = useCallback(() => defaultValue, [defaultValue]);
+  const value = useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+  const set = useCallback(
+    (next) => {
+      const { serialize: encode, parse: decode, defaultValue: fallback } = latest.current;
+      try {
+        const resolved = typeof next === "function" ? next(parseOr(readCurrent(kind, key), decode, fallback)) : next;
+        writeCurrent(kind, key, encode(resolved));
+      } catch {
+      }
+    },
+    [kind, key]
+  );
+  const remove = useCallback(() => removeCurrent(kind, key), [kind, key]);
+  return [value, set, remove];
+}
+
+export {
+  useStorageState
+};

package/dist/chunk-6KCRVSLS.js

@@ -0,0 +1,80 @@
+"use client";
+
+// src/scroll-lock/use-scroll-lock.ts
+import { useEffect } from "react";
+
+// src/scroll-lock/lock-styles.ts
+var LOCKED_PROPERTIES = [
+  "position",
+  "top",
+  "left",
+  "right",
+  "width",
+  "overflow",
+  "paddingRight"
+];
+function computeLockStyles({ scrollY, scrollbarWidth, existingPaddingRight }) {
+  const styles = {
+    position: "fixed",
+    top: `-${scrollY}px`,
+    left: "0",
+    right: "0",
+    width: "100%",
+    overflow: "hidden"
+  };
+  if (scrollbarWidth > 0) styles.paddingRight = `${existingPaddingRight + scrollbarWidth}px`;
+  return styles;
+}
+
+// src/scroll-lock/scroll-lock.ts
+var count = 0;
+var saved = null;
+function applyFirstLock() {
+  const { body, documentElement } = document;
+  const inline = {};
+  for (const property of LOCKED_PROPERTIES) inline[property] = body.style[property];
+  saved = { scrollY: window.scrollY, inline };
+  const styles = computeLockStyles({
+    scrollY: saved.scrollY,
+    scrollbarWidth: Math.max(0, window.innerWidth - documentElement.clientWidth),
+    existingPaddingRight: parseFloat(getComputedStyle(body).paddingRight) || 0
+  });
+  Object.assign(body.style, styles);
+}
+function restoreLastLock() {
+  if (!saved) return;
+  const { scrollY, inline } = saved;
+  saved = null;
+  Object.assign(document.body.style, inline);
+  window.scrollTo(0, scrollY);
+}
+function lockScroll() {
+  if (count === 0) applyFirstLock();
+  count += 1;
+  let released = false;
+  return () => {
+    if (released) return;
+    released = true;
+    count -= 1;
+    if (count === 0) restoreLastLock();
+  };
+}
+function unlockScroll() {
+  if (count === 0) return;
+  count -= 1;
+  if (count === 0) restoreLastLock();
+}
+
+// src/scroll-lock/use-scroll-lock.ts
+function useScrollLock(active = true) {
+  useEffect(() => {
+    if (!active) return;
+    return lockScroll();
+  }, [active]);
+}
+
+export {
+  lockScroll,
+  unlockScroll,
+  useScrollLock
+};