@lacspace/hooks 1.0.0

package/LICENSE

@@ -0,0 +1,51 @@
+Lacspace Free Licence
+Version 1.0, August 2026
+
+Copyright (c) 2026 Lacspace
+
+PREAMBLE
+
+This software is published by Lacspace under the Lacspace Free Licence — a free,
+permissive licence that lets you use this software for any purpose, including in
+commercial products and services, at no cost. It grants the same freedoms as
+common permissive open-source licences; the only condition is that this notice
+travels with the software. The canonical, always-current text of this licence is
+maintained at https://lacspace.com/licenses/lacspace-free-1.0
+
+GRANT OF RIGHTS
+
+Permission is hereby granted, free of charge, to any person or organisation
+obtaining a copy of this software and its associated documentation and data 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 conditions below. These rights are
+granted for any purpose, personal or commercial, and are perpetual, worldwide,
+non-exclusive, and royalty-free.
+
+CONDITIONS
+
+The above copyright notice, this permission notice, and the name of this licence
+("Lacspace Free Licence") shall be included in all copies or substantial portions
+of the Software.
+
+TRADEMARKS
+
+This licence does not grant permission to use the trade names, trademarks, service
+marks, logos, or product names of Lacspace, except as required to reproduce the
+notice above or to describe the origin of the Software in a truthful manner.
+
+DISCLAIMER OF WARRANTY AND LIMITATION OF LIABILITY
+
+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.
+
+---
+
+The Lacspace Free Licence is a source-available, permissive licence and is not (as
+of this version) an OSI-approved licence. In substance it grants the same freedoms
+as the MIT Licence. Learn more at https://lacspace.com/licenses

package/README.md

@@ -0,0 +1,123 @@
+# @lacspace/hooks
+
+**Essential, SSR-safe React hooks — everything you reach for, zero dependencies.**
+
+## Install
+
+```sh
+npm i @lacspace/hooks
+```
+
+`react` (`>=18`) is a **peer dependency** — you already have it in your app.
+
+## Usage
+
+Persist state to `localStorage` (SSR-safe, syncs across tabs):
+
+```tsx
+import { useLocalStorage } from "@lacspace/hooks";
+
+function ThemeToggle() {
+  const [theme, setTheme] = useLocalStorage("theme", "light");
+  return (
+    <button onClick={() => setTheme((t) => (t === "light" ? "dark" : "light"))}>
+      {theme}
+    </button>
+  );
+}
+```
+
+Debounce a search box:
+
+```tsx
+import { useState } from "react";
+import { useDebounce } from "@lacspace/hooks";
+
+function Search() {
+  const [query, setQuery] = useState("");
+  const debounced = useDebounce(query, 300);
+  // ...run the query effect on `debounced`
+  return <input value={query} onChange={(e) => setQuery(e.target.value)} />;
+}
+```
+
+Close a menu when clicking outside:
+
+```tsx
+import { useRef } from "react";
+import { useOnClickOutside } from "@lacspace/hooks";
+
+function Menu({ onClose }: { onClose: () => void }) {
+  const ref = useRef<HTMLDivElement>(null);
+  useOnClickOutside(ref, onClose);
+  return <div ref={ref}>…</div>;
+}
+```
+
+React to a media query and copy to the clipboard:
+
+```tsx
+import { useMediaQuery, useCopyToClipboard } from "@lacspace/hooks";
+
+function Share({ url }: { url: string }) {
+  const isDark = useMediaQuery("(prefers-color-scheme: dark)");
+  const [copied, copy] = useCopyToClipboard();
+  return (
+    <button data-dark={isDark} onClick={() => copy(url)}>
+      {copied ? "Copied!" : "Copy link"}
+    </button>
+  );
+}
+```
+
+## All hooks
+
+| Hook | What it does |
+| --- | --- |
+| `useIsomorphicLayoutEffect` | `useLayoutEffect` on the client, `useEffect` on the server |
+| `useIsMounted` | Stable getter for whether the component is still mounted |
+| `useMountEffect` | Runs an effect once, on mount |
+| `useUpdateEffect` | Like `useEffect` but skips the first run |
+| `usePrevious` | The value from the previous render |
+| `useLocalStorage` | JSON `localStorage` state — SSR-safe, cross-tab sync, `remove()` |
+| `useSessionStorage` | Same contract, backed by `sessionStorage` |
+| `useDebounce` | Debounced copy of a value |
+| `useDebouncedCallback` | Debounced callback with `.cancel()` |
+| `useThrottle` | Throttled copy of a value |
+| `useToggle` | Boolean state with `toggle/on/off/set` |
+| `useCounter` | Numeric state with `inc/dec/set/reset` |
+| `useDisclosure` | Open/close state for modals, drawers, menus |
+| `useInterval` | `setInterval` with a latest-callback ref; pause with `null` |
+| `useTimeout` | `setTimeout` with a latest-callback ref; cancel with `null` |
+| `useMediaQuery` | Tracks a CSS media query (SSR-safe) |
+| `useWindowSize` | Current viewport `{ width, height }` (SSR-safe) |
+| `useScrollPosition` | Current window scroll `{ x, y }` (SSR-safe) |
+| `useEventListener` | Typed listener for `window`, `document`, or a ref/element |
+| `useOnClickOutside` | Fires when a pointer event lands outside a ref |
+| `useHover` | `[ref, hovered]` hover tracking |
+| `useIntersectionObserver` | `[ref, isIntersecting, entry]` viewport observing |
+| `useKeyPress` | `true` while a given key is held |
+| `useCopyToClipboard` | `[copied, copy]` with a safe `execCommand` fallback |
+| `useDocumentTitle` | Sets `document.title` while mounted |
+| `useOnlineStatus` | Tracks online/offline (SSR-safe, `true` on server) |
+| `useIdle` | `true` after N ms of no user activity |
+| `useLockBodyScroll` | Locks body scroll while active, restores on cleanup |
+
+## Why it's tiny
+
+- **Zero runtime dependencies** — nothing but React, which you already ship.
+- **Tree-shakeable** — `sideEffects: false` and per-hook exports; bundle only what you import.
+- **Isomorphic / SSR-safe** — no `window`, `document`, or storage access at module load or during render; safe under Next.js, Remix, and any server renderer.
+- **Fully typed** — strict TypeScript with complete `.d.ts` for ESM and CJS.
+
+## Licensing
+
+Free under the **[Lacspace Free Licence](https://lacspace.com/licenses/lacspace-free-1.0)** — MIT-equivalent freedoms. Use it in personal and commercial projects at no cost; just keep the notice. See the **[Lacspace Licence Centre](https://lacspace.com/licenses)**.
+
+---
+
+**Part of the Lacspace ecosystem — zero-dependency, isomorphic TypeScript packages.**
+
+[All packages ↗](https://lacspace.com/packages) · [npm org ↗](https://www.npmjs.com/org/lacspace) · [Licence Centre ↗](https://lacspace.com/licenses) · [GitHub ↗](https://github.com/lacspace/npm-packages)
+
+<div align="center"><sub>Built with care by <a href="https://lacspace.com">Lacspace</a> · Lacspace Free Licence · <a href="https://github.com/lacspace/npm-packages">source</a></sub></div>

package/dist/index.cjs

@@ -0,0 +1,444 @@
+'use strict';
+
+var react = require('react');
+
+// src/index.ts
+var isBrowser = typeof window !== "undefined";
+var useIsomorphicLayoutEffect = isBrowser ? react.useLayoutEffect : react.useEffect;
+function useIsMounted() {
+  const mounted = react.useRef(false);
+  react.useEffect(() => {
+    mounted.current = true;
+    return () => {
+      mounted.current = false;
+    };
+  }, []);
+  return react.useCallback(() => mounted.current, []);
+}
+function useMountEffect(effect) {
+  react.useEffect(effect, []);
+}
+function useUpdateEffect(effect, deps) {
+  const isFirst = react.useRef(true);
+  react.useEffect(() => {
+    if (isFirst.current) {
+      isFirst.current = false;
+      return;
+    }
+    return effect();
+  }, deps);
+}
+function usePrevious(value) {
+  const ref = react.useRef(void 0);
+  react.useEffect(() => {
+    ref.current = value;
+  }, [value]);
+  return ref.current;
+}
+function useStorage(storageArea, key, initialValue) {
+  const readValue = react.useCallback(() => {
+    if (!isBrowser) return initialValue;
+    try {
+      const raw = window[storageArea].getItem(key);
+      return raw === null ? initialValue : JSON.parse(raw);
+    } catch {
+      return initialValue;
+    }
+  }, [initialValue, key, storageArea]);
+  const [storedValue, setStoredValue] = react.useState(initialValue);
+  react.useEffect(() => {
+    setStoredValue(readValue());
+  }, [key]);
+  const setValue = react.useCallback(
+    (value) => {
+      setStoredValue((prev) => {
+        const next = value instanceof Function ? value(prev) : value;
+        if (isBrowser) {
+          try {
+            window[storageArea].setItem(key, JSON.stringify(next));
+            window.dispatchEvent(
+              new StorageEvent("storage", { key, newValue: JSON.stringify(next) })
+            );
+          } catch {
+          }
+        }
+        return next;
+      });
+    },
+    [key, storageArea]
+  );
+  const remove = react.useCallback(() => {
+    if (isBrowser) {
+      try {
+        window[storageArea].removeItem(key);
+        window.dispatchEvent(new StorageEvent("storage", { key, newValue: null }));
+      } catch {
+      }
+    }
+    setStoredValue(initialValue);
+  }, [initialValue, key, storageArea]);
+  react.useEffect(() => {
+    if (!isBrowser) return;
+    const onStorage = (e) => {
+      if (e.key !== null && e.key !== key) return;
+      setStoredValue(readValue());
+    };
+    window.addEventListener("storage", onStorage);
+    return () => window.removeEventListener("storage", onStorage);
+  }, [key, readValue]);
+  return [storedValue, setValue, remove];
+}
+function useLocalStorage(key, initialValue) {
+  return useStorage("localStorage", key, initialValue);
+}
+function useSessionStorage(key, initialValue) {
+  return useStorage("sessionStorage", key, initialValue);
+}
+function useDebounce(value, delayMs) {
+  const [debounced, setDebounced] = react.useState(value);
+  react.useEffect(() => {
+    const id = setTimeout(() => setDebounced(value), delayMs);
+    return () => clearTimeout(id);
+  }, [value, delayMs]);
+  return debounced;
+}
+function useDebouncedCallback(fn, delayMs) {
+  const fnRef = react.useRef(fn);
+  useIsomorphicLayoutEffect(() => {
+    fnRef.current = fn;
+  }, [fn]);
+  const timeout = react.useRef(null);
+  const cancel = react.useCallback(() => {
+    if (timeout.current !== null) {
+      clearTimeout(timeout.current);
+      timeout.current = null;
+    }
+  }, []);
+  react.useEffect(() => cancel, [cancel]);
+  const debounced = react.useCallback(
+    (...args) => {
+      if (timeout.current !== null) clearTimeout(timeout.current);
+      timeout.current = setTimeout(() => {
+        timeout.current = null;
+        fnRef.current(...args);
+      }, delayMs);
+    },
+    [delayMs]
+  );
+  debounced.cancel = cancel;
+  return debounced;
+}
+function useThrottle(value, ms) {
+  const [throttled, setThrottled] = react.useState(value);
+  const lastRan = react.useRef(isBrowser ? Date.now() : 0);
+  react.useEffect(() => {
+    const remaining = ms - (Date.now() - lastRan.current);
+    if (remaining <= 0) {
+      setThrottled(value);
+      lastRan.current = Date.now();
+      return;
+    }
+    const id = setTimeout(() => {
+      setThrottled(value);
+      lastRan.current = Date.now();
+    }, remaining);
+    return () => clearTimeout(id);
+  }, [value, ms]);
+  return throttled;
+}
+function useInterval(callback, delayMs) {
+  const saved = react.useRef(callback);
+  useIsomorphicLayoutEffect(() => {
+    saved.current = callback;
+  }, [callback]);
+  react.useEffect(() => {
+    if (delayMs === null) return;
+    const id = setInterval(() => saved.current(), delayMs);
+    return () => clearInterval(id);
+  }, [delayMs]);
+}
+function useTimeout(callback, delayMs) {
+  const saved = react.useRef(callback);
+  useIsomorphicLayoutEffect(() => {
+    saved.current = callback;
+  }, [callback]);
+  react.useEffect(() => {
+    if (delayMs === null) return;
+    const id = setTimeout(() => saved.current(), delayMs);
+    return () => clearTimeout(id);
+  }, [delayMs]);
+}
+function useToggle(initial = false) {
+  const [value, setValue] = react.useState(initial);
+  const toggle = react.useCallback(() => setValue((v) => !v), []);
+  const on = react.useCallback(() => setValue(true), []);
+  const off = react.useCallback(() => setValue(false), []);
+  const set = react.useCallback((v) => setValue(v), []);
+  return [value, { toggle, on, off, set }];
+}
+function useCounter(initial = 0) {
+  const [count, setCount] = react.useState(initial);
+  const inc = react.useCallback((step = 1) => setCount((c) => c + step), []);
+  const dec = react.useCallback((step = 1) => setCount((c) => c - step), []);
+  const set = react.useCallback((n) => setCount(n), []);
+  const reset = react.useCallback(() => setCount(initial), [initial]);
+  return { count, inc, dec, set, reset };
+}
+function useDisclosure(initial = false) {
+  const [isOpen, setOpen] = react.useState(initial);
+  const open = react.useCallback(() => setOpen(true), []);
+  const close = react.useCallback(() => setOpen(false), []);
+  const toggle = react.useCallback(() => setOpen((v) => !v), []);
+  return { isOpen, open, close, toggle };
+}
+function useMediaQuery(query) {
+  const [matches, setMatches] = react.useState(false);
+  react.useEffect(() => {
+    if (!isBrowser || typeof window.matchMedia !== "function") return;
+    const mql = window.matchMedia(query);
+    const onChange = () => setMatches(mql.matches);
+    onChange();
+    mql.addEventListener("change", onChange);
+    return () => mql.removeEventListener("change", onChange);
+  }, [query]);
+  return matches;
+}
+function useWindowSize() {
+  const [size, setSize] = react.useState({
+    width: 0,
+    height: 0
+  });
+  react.useEffect(() => {
+    if (!isBrowser) return;
+    const onResize = () => setSize({ width: window.innerWidth, height: window.innerHeight });
+    onResize();
+    window.addEventListener("resize", onResize);
+    return () => window.removeEventListener("resize", onResize);
+  }, []);
+  return size;
+}
+function useScrollPosition() {
+  const [pos, setPos] = react.useState({ x: 0, y: 0 });
+  react.useEffect(() => {
+    if (!isBrowser) return;
+    const onScroll = () => setPos({ x: window.scrollX, y: window.scrollY });
+    onScroll();
+    window.addEventListener("scroll", onScroll, { passive: true });
+    return () => window.removeEventListener("scroll", onScroll);
+  }, []);
+  return pos;
+}
+function useEventListener(type, handler, element, options) {
+  const savedHandler = react.useRef(handler);
+  useIsomorphicLayoutEffect(() => {
+    savedHandler.current = handler;
+  }, [handler]);
+  react.useEffect(() => {
+    if (!isBrowser) return;
+    const target = element == null ? window : "current" in element ? element.current : element;
+    if (target == null || typeof target.addEventListener !== "function") return;
+    const listener = (event) => savedHandler.current(event);
+    target.addEventListener(type, listener, options);
+    return () => target.removeEventListener(type, listener, options);
+  }, [type, element, options]);
+}
+function useOnClickOutside(ref, handler) {
+  const savedHandler = react.useRef(handler);
+  useIsomorphicLayoutEffect(() => {
+    savedHandler.current = handler;
+  }, [handler]);
+  react.useEffect(() => {
+    if (!isBrowser) return;
+    const listener = (event) => {
+      const el = ref.current;
+      const target = event.target;
+      if (el == null || target == null || el.contains(target)) return;
+      savedHandler.current(event);
+    };
+    document.addEventListener("mousedown", listener);
+    document.addEventListener("touchstart", listener, { passive: true });
+    return () => {
+      document.removeEventListener("mousedown", listener);
+      document.removeEventListener("touchstart", listener);
+    };
+  }, [ref]);
+}
+function useHover() {
+  const ref = react.useRef(null);
+  const [hovered, setHovered] = react.useState(false);
+  react.useEffect(() => {
+    const node = ref.current;
+    if (node == null) return;
+    const onEnter = () => setHovered(true);
+    const onLeave = () => setHovered(false);
+    node.addEventListener("mouseenter", onEnter);
+    node.addEventListener("mouseleave", onLeave);
+    return () => {
+      node.removeEventListener("mouseenter", onEnter);
+      node.removeEventListener("mouseleave", onLeave);
+    };
+  });
+  return [ref, hovered];
+}
+function useIntersectionObserver(options) {
+  const ref = react.useRef(null);
+  const [entry, setEntry] = react.useState(null);
+  const { root, rootMargin, threshold } = options ?? {};
+  react.useEffect(() => {
+    const node = ref.current;
+    if (!isBrowser || typeof IntersectionObserver !== "function" || node == null) {
+      return;
+    }
+    const observer = new IntersectionObserver(
+      (entries) => {
+        const first = entries[0];
+        if (first) setEntry(first);
+      },
+      { root, rootMargin, threshold }
+    );
+    observer.observe(node);
+    return () => observer.disconnect();
+  }, [root, rootMargin, JSON.stringify(threshold)]);
+  return [ref, (entry == null ? void 0 : entry.isIntersecting) ?? false, entry];
+}
+function useKeyPress(targetKey) {
+  const [pressed, setPressed] = react.useState(false);
+  react.useEffect(() => {
+    if (!isBrowser) return;
+    const down = (e) => {
+      if (e.key === targetKey) setPressed(true);
+    };
+    const up = (e) => {
+      if (e.key === targetKey) setPressed(false);
+    };
+    window.addEventListener("keydown", down);
+    window.addEventListener("keyup", up);
+    return () => {
+      window.removeEventListener("keydown", down);
+      window.removeEventListener("keyup", up);
+    };
+  }, [targetKey]);
+  return pressed;
+}
+function useCopyToClipboard() {
+  const [copied, setCopied] = react.useState(null);
+  const copy = react.useCallback(async (text) => {
+    if (!isBrowser) return false;
+    try {
+      if (navigator.clipboard && typeof navigator.clipboard.writeText === "function") {
+        await navigator.clipboard.writeText(text);
+        setCopied(text);
+        return true;
+      }
+    } catch {
+    }
+    try {
+      const el = document.createElement("textarea");
+      el.value = text;
+      el.setAttribute("readonly", "");
+      el.style.position = "absolute";
+      el.style.left = "-9999px";
+      document.body.appendChild(el);
+      el.select();
+      const ok = document.execCommand("copy");
+      document.body.removeChild(el);
+      if (ok) {
+        setCopied(text);
+        return true;
+      }
+    } catch {
+    }
+    setCopied(null);
+    return false;
+  }, []);
+  return [copied, copy];
+}
+function useDocumentTitle(title) {
+  useIsomorphicLayoutEffect(() => {
+    if (!isBrowser) return;
+    document.title = title;
+  }, [title]);
+}
+function useOnlineStatus() {
+  const [online, setOnline] = react.useState(true);
+  react.useEffect(() => {
+    if (!isBrowser) return;
+    const update = () => setOnline(navigator.onLine);
+    update();
+    window.addEventListener("online", update);
+    window.addEventListener("offline", update);
+    return () => {
+      window.removeEventListener("online", update);
+      window.removeEventListener("offline", update);
+    };
+  }, []);
+  return online;
+}
+function useIdle(ms) {
+  const [idle, setIdle] = react.useState(false);
+  react.useEffect(() => {
+    if (!isBrowser) return;
+    let timer;
+    const reset = () => {
+      setIdle(false);
+      clearTimeout(timer);
+      timer = setTimeout(() => setIdle(true), ms);
+    };
+    const events = [
+      "mousemove",
+      "mousedown",
+      "keydown",
+      "touchstart",
+      "scroll",
+      "wheel"
+    ];
+    events.forEach((e) => window.addEventListener(e, reset, { passive: true }));
+    reset();
+    return () => {
+      clearTimeout(timer);
+      events.forEach((e) => window.removeEventListener(e, reset));
+    };
+  }, [ms]);
+  return idle;
+}
+function useLockBodyScroll(locked = true) {
+  useIsomorphicLayoutEffect(() => {
+    if (!isBrowser || !locked) return;
+    const original = document.body.style.overflow;
+    document.body.style.overflow = "hidden";
+    return () => {
+      document.body.style.overflow = original;
+    };
+  }, [locked]);
+}
+
+exports.useCopyToClipboard = useCopyToClipboard;
+exports.useCounter = useCounter;
+exports.useDebounce = useDebounce;
+exports.useDebouncedCallback = useDebouncedCallback;
+exports.useDisclosure = useDisclosure;
+exports.useDocumentTitle = useDocumentTitle;
+exports.useEventListener = useEventListener;
+exports.useHover = useHover;
+exports.useIdle = useIdle;
+exports.useIntersectionObserver = useIntersectionObserver;
+exports.useInterval = useInterval;
+exports.useIsMounted = useIsMounted;
+exports.useIsomorphicLayoutEffect = useIsomorphicLayoutEffect;
+exports.useKeyPress = useKeyPress;
+exports.useLocalStorage = useLocalStorage;
+exports.useLockBodyScroll = useLockBodyScroll;
+exports.useMediaQuery = useMediaQuery;
+exports.useMountEffect = useMountEffect;
+exports.useOnClickOutside = useOnClickOutside;
+exports.useOnlineStatus = useOnlineStatus;
+exports.usePrevious = usePrevious;
+exports.useScrollPosition = useScrollPosition;
+exports.useSessionStorage = useSessionStorage;
+exports.useThrottle = useThrottle;
+exports.useTimeout = useTimeout;
+exports.useToggle = useToggle;
+exports.useUpdateEffect = useUpdateEffect;
+exports.useWindowSize = useWindowSize;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map