@-reddacted-/react-hooks 0.1.0 → 0.3.0

package/dist/index.d.ts

@@ -1,5 +1,12 @@
-export { useFullscreen } from "./useFullscreen";
-export { useInstallPrompt } from "./useInstallPrompt";
-export type { UseInstallPromptOptions } from "./useInstallPrompt";
-export { useValueChange } from "./useValueChange";
+export { useFullscreen } from "./useFullscreen.js";
+export { useInstallPrompt, type UseInstallPromptOptions } from "./useInstallPrompt.js";
+export { useValueChange } from "./useValueChange.js";
+export { useAsync, type AsyncStatus, type AsyncResult } from "./useAsync.js";
+export { useElementSize, type ElementSize } from "./useElementSize.js";
+export { useClickOutside } from "./useClickOutside.js";
+export { useEscapeKey } from "./useEscapeKey.js";
+export { useDocumentTitle } from "./useDocumentTitle.js";
+export { useFocusTrap } from "./useFocusTrap.js";
+export { useScrollLock } from "./useScrollLock.js";
+export { useOverlayStack } from "./useOverlayStack.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AAC/C,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAA;AACrD,YAAY,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAA;AACjE,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAClD,OAAO,EAAE,gBAAgB,EAAE,KAAK,uBAAuB,EAAE,MAAM,uBAAuB,CAAA;AACtF,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AACpD,OAAO,EAAE,QAAQ,EAAE,KAAK,WAAW,EAAE,KAAK,WAAW,EAAE,MAAM,eAAe,CAAA;AAC5E,OAAO,EAAE,cAAc,EAAE,KAAK,WAAW,EAAE,MAAM,qBAAqB,CAAA;AACtE,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AACtD,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAChD,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AACxD,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAClD,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA"}

package/dist/index.js

@@ -1,3 +1,11 @@
-export { useFullscreen } from "./useFullscreen";
-export { useInstallPrompt } from "./useInstallPrompt";
-export { useValueChange } from "./useValueChange";
+export { useFullscreen } from "./useFullscreen.js";
+export { useInstallPrompt } from "./useInstallPrompt.js";
+export { useValueChange } from "./useValueChange.js";
+export { useAsync } from "./useAsync.js";
+export { useElementSize } from "./useElementSize.js";
+export { useClickOutside } from "./useClickOutside.js";
+export { useEscapeKey } from "./useEscapeKey.js";
+export { useDocumentTitle } from "./useDocumentTitle.js";
+export { useFocusTrap } from "./useFocusTrap.js";
+export { useScrollLock } from "./useScrollLock.js";
+export { useOverlayStack } from "./useOverlayStack.js";

package/dist/useAsync.d.ts

@@ -0,0 +1,18 @@
+import type { DependencyList } from "react";
+export type AsyncStatus = "loading" | "ready" | "error";
+export type AsyncResult<T> = {
+    data: T | null;
+    status: AsyncStatus;
+    error: unknown;
+    /** Runs the task again. Wire it to a retry button. */
+    retry: () => void;
+};
+/**
+ * Runs an abortable async task and tracks its three states.
+ *
+ * The task receives an AbortSignal that fires when the dependencies change or the
+ * component unmounts, so a stale response can never overwrite a fresh one. An aborted
+ * task is not an error and leaves the state untouched.
+ */
+export declare function useAsync<T>(task: (signal: AbortSignal) => Promise<T>, deps?: DependencyList): AsyncResult<T>;
+//# sourceMappingURL=useAsync.d.ts.map

package/dist/useAsync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useAsync.d.ts","sourceRoot":"","sources":["../src/useAsync.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,OAAO,CAAA;AAE3C,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,OAAO,GAAG,OAAO,CAAA;AAEvD,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI;IAC3B,IAAI,EAAE,CAAC,GAAG,IAAI,CAAA;IACd,MAAM,EAAE,WAAW,CAAA;IACnB,KAAK,EAAE,OAAO,CAAA;IACd,sDAAsD;IACtD,KAAK,EAAE,MAAM,IAAI,CAAA;CAClB,CAAA;AAQD;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,EAAE,IAAI,GAAE,cAAmB,GAAG,WAAW,CAAC,CAAC,CAAC,CAmChH"}

package/dist/useAsync.js

@@ -0,0 +1,39 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+function isAbort(cause) {
+    return cause instanceof Error && cause.name === "AbortError";
+}
+/**
+ * Runs an abortable async task and tracks its three states.
+ *
+ * The task receives an AbortSignal that fires when the dependencies change or the
+ * component unmounts, so a stale response can never overwrite a fresh one. An aborted
+ * task is not an error and leaves the state untouched.
+ */
+export function useAsync(task, deps = []) {
+    const [state, setState] = useState({ data: null, status: "loading", error: null });
+    const [attempt, setAttempt] = useState(0);
+    // La tâche est le plus souvent une closure recréée à chaque rendu : la garder dans un
+    // ref laisse les dépendances déclarées seules maîtresses du redéclenchement.
+    const taskRef = useRef(task);
+    taskRef.current = task;
+    useEffect(() => {
+        const controller = new AbortController();
+        let active = true;
+        setState(current => ({ ...current, status: "loading" }));
+        taskRef.current(controller.signal).then(data => {
+            if (active)
+                setState({ data, status: "ready", error: null });
+        }, error => {
+            if (!active || controller.signal.aborted || isAbort(error))
+                return;
+            setState({ data: null, status: "error", error });
+        });
+        return () => {
+            active = false;
+            controller.abort();
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [...deps, attempt]);
+    const retry = useCallback(() => setAttempt(n => n + 1), []);
+    return { ...state, retry };
+}

package/dist/useClickOutside.d.ts

@@ -0,0 +1,9 @@
+import type { RefObject } from "react";
+/**
+ * Calls the handler on a pointer press outside every given element.
+ *
+ * Listens on mousedown rather than click: a press that starts outside and ends inside
+ * should still dismiss, and the handler runs before the target rerenders.
+ */
+export declare function useClickOutside(refs: Array<RefObject<HTMLElement | null>>, handler: () => void, enabled?: boolean): void;
+//# sourceMappingURL=useClickOutside.d.ts.map

package/dist/useClickOutside.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useClickOutside.d.ts","sourceRoot":"","sources":["../src/useClickOutside.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAEtC;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,KAAK,CAAC,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC,EAC1C,OAAO,EAAE,MAAM,IAAI,EACnB,OAAO,UAAO,GACb,IAAI,CAcN"}

package/dist/useClickOutside.js

@@ -0,0 +1,22 @@
+import { useEffect } from "react";
+/**
+ * Calls the handler on a pointer press outside every given element.
+ *
+ * Listens on mousedown rather than click: a press that starts outside and ends inside
+ * should still dismiss, and the handler runs before the target rerenders.
+ */
+export function useClickOutside(refs, handler, enabled = true) {
+    useEffect(() => {
+        if (!enabled)
+            return;
+        const onMouseDown = (event) => {
+            const target = event.target;
+            if (refs.some(ref => ref.current?.contains(target)))
+                return;
+            handler();
+        };
+        document.addEventListener("mousedown", onMouseDown);
+        return () => document.removeEventListener("mousedown", onMouseDown);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [enabled, handler, ...refs]);
+}

package/dist/useDocumentTitle.d.ts

@@ -0,0 +1,2 @@
+export declare function useDocumentTitle(title: string | undefined, siteName: string, fallback?: string): void;
+//# sourceMappingURL=useDocumentTitle.d.ts.map

package/dist/useDocumentTitle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useDocumentTitle.d.ts","sourceRoot":"","sources":["../src/useDocumentTitle.ts"],"names":[],"mappings":"AAIA,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,QAI9F"}

package/dist/useDocumentTitle.js

@@ -0,0 +1,8 @@
+import { useEffect } from "react";
+// Without this every page shares the title of index.html in the tab, the history
+// and the search results.
+export function useDocumentTitle(title, siteName, fallback) {
+    useEffect(() => {
+        document.title = title ? `${title} — ${siteName}` : (fallback ?? siteName);
+    }, [title, siteName, fallback]);
+}

package/dist/useElementSize.d.ts

@@ -0,0 +1,13 @@
+import type { RefObject } from "react";
+export type ElementSize = {
+    width: number;
+    height: number;
+};
+/**
+ * Observed size of an element. Null until the first measure.
+ *
+ * useLayoutEffect rather than useEffect: the first measure lands before paint, so a
+ * layout that depends on it never flashes at a default size before settling.
+ */
+export declare function useElementSize(ref: RefObject<HTMLElement | null>): ElementSize | null;
+//# sourceMappingURL=useElementSize.d.ts.map

package/dist/useElementSize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useElementSize.d.ts","sourceRoot":"","sources":["../src/useElementSize.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAEtC,MAAM,MAAM,WAAW,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAA;AAE3D;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,GAAG,WAAW,GAAG,IAAI,CAsBrF"}

package/dist/useElementSize.js

@@ -0,0 +1,26 @@
+import { useLayoutEffect, useState } from "react";
+/**
+ * Observed size of an element. Null until the first measure.
+ *
+ * useLayoutEffect rather than useEffect: the first measure lands before paint, so a
+ * layout that depends on it never flashes at a default size before settling.
+ */
+export function useElementSize(ref) {
+    const [size, setSize] = useState(null);
+    useLayoutEffect(() => {
+        const element = ref.current;
+        if (!element)
+            return;
+        const measure = ({ width, height }) => setSize({ width, height });
+        const rect = element.getBoundingClientRect();
+        measure({ width: rect.width, height: rect.height });
+        const observer = new ResizeObserver(entries => {
+            const rect = entries[0]?.contentRect;
+            if (rect)
+                measure({ width: rect.width, height: rect.height });
+        });
+        observer.observe(element);
+        return () => observer.disconnect();
+    }, [ref]);
+    return size;
+}

package/dist/useEscapeKey.d.ts

@@ -0,0 +1,2 @@
+export declare function useEscapeKey(handler: () => void, enabled?: boolean): void;
+//# sourceMappingURL=useEscapeKey.d.ts.map

package/dist/useEscapeKey.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useEscapeKey.d.ts","sourceRoot":"","sources":["../src/useEscapeKey.ts"],"names":[],"mappings":"AAEA,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,IAAI,EAAE,OAAO,UAAO,GAAG,IAAI,CAWtE"}

package/dist/useEscapeKey.js

@@ -0,0 +1,13 @@
+import { useEffect } from "react";
+export function useEscapeKey(handler, enabled = true) {
+    useEffect(() => {
+        if (!enabled)
+            return;
+        const onKeyDown = (event) => {
+            if (event.key === "Escape")
+                handler();
+        };
+        document.addEventListener("keydown", onKeyDown);
+        return () => document.removeEventListener("keydown", onKeyDown);
+    }, [enabled, handler]);
+}

package/dist/useFocusTrap.d.ts

@@ -0,0 +1,11 @@
+import type { RefObject } from "react";
+/**
+ * Keeps the focus inside `ref` while `enabled`: focuses its first focusable element
+ * (or the container itself) on activation, loops Tab / Shift+Tab, pulls back a focus
+ * that escaped, and restores the previously focused element on deactivation.
+ * The container should have `tabIndex={-1}` so it can receive the focus.
+ * `paused` suspends Tab looping and focus rescue without releasing the trap, e.g. while
+ * another overlay (menu, drawer) is open above.
+ */
+export declare function useFocusTrap(ref: RefObject<HTMLElement | null>, enabled?: boolean, paused?: boolean): void;
+//# sourceMappingURL=useFocusTrap.d.ts.map

package/dist/useFocusTrap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useFocusTrap.d.ts","sourceRoot":"","sources":["../src/useFocusTrap.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AActC;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,EAAE,OAAO,UAAO,EAAE,MAAM,UAAQ,GAAG,IAAI,CA0DrG"}

package/dist/useFocusTrap.js

@@ -0,0 +1,74 @@
+import { useEffect, useRef } from "react";
+const FOCUSABLE = `a[href], button, textarea, input, select, [tabindex]:not([tabindex="-1"])`;
+// Active traps, last activated last: only that one handles Tab and focus rescue,
+// so nested overlays (a Modal over a Drawer) don't fight over the focus.
+const traps = [];
+function getFocusables(container) {
+    return Array.from(container.querySelectorAll(FOCUSABLE)).filter(el => !el.hasAttribute("disabled") && !el.getAttribute("aria-hidden"));
+}
+/**
+ * Keeps the focus inside `ref` while `enabled`: focuses its first focusable element
+ * (or the container itself) on activation, loops Tab / Shift+Tab, pulls back a focus
+ * that escaped, and restores the previously focused element on deactivation.
+ * The container should have `tabIndex={-1}` so it can receive the focus.
+ * `paused` suspends Tab looping and focus rescue without releasing the trap, e.g. while
+ * another overlay (menu, drawer) is open above.
+ */
+export function useFocusTrap(ref, enabled = true, paused = false) {
+    const pausedRef = useRef(paused);
+    pausedRef.current = paused;
+    useEffect(() => {
+        if (!enabled)
+            return;
+        const key = Symbol("focus-trap");
+        traps.push(key);
+        const isActive = () => !pausedRef.current && traps[traps.length - 1] === key;
+        const previouslyFocused = document.activeElement;
+        // Deferred: the container may not be focusable yet in the commit that enables the trap.
+        const timeout = setTimeout(() => {
+            const container = ref.current;
+            if (!container)
+                return;
+            (getFocusables(container)[0] ?? container).focus();
+        }, 0);
+        const onKeyDown = (event) => {
+            if (event.key !== "Tab" || !isActive())
+                return;
+            const container = ref.current;
+            if (!container)
+                return;
+            const focusables = getFocusables(container);
+            if (focusables.length === 0)
+                return;
+            const first = focusables[0];
+            const last = focusables[focusables.length - 1];
+            const active = document.activeElement;
+            if (event.shiftKey) {
+                if (active === first || !container.contains(active)) {
+                    last.focus();
+                    event.preventDefault();
+                }
+            }
+            else if (active === last || !container.contains(active)) {
+                first.focus();
+                event.preventDefault();
+            }
+        };
+        const onFocusIn = (event) => {
+            if (!isActive())
+                return;
+            const container = ref.current;
+            if (container && !container.contains(event.target))
+                container.focus();
+        };
+        document.addEventListener("keydown", onKeyDown);
+        document.addEventListener("focusin", onFocusIn);
+        return () => {
+            clearTimeout(timeout);
+            document.removeEventListener("keydown", onKeyDown);
+            document.removeEventListener("focusin", onFocusIn);
+            traps.splice(traps.indexOf(key), 1);
+            previouslyFocused?.focus?.();
+        };
+    }, [enabled, ref]);
+}

package/dist/useOverlayStack.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Registers an overlay in a page-wide stack while `enabled`.
+ * `isTop` is true for the last opened overlay only (the one that should react to Escape);
+ * `zIndex` puts every overlay above the ones opened before it.
+ */
+export declare function useOverlayStack(enabled?: boolean): {
+    isTop: boolean;
+    zIndex: number;
+};
+//# sourceMappingURL=useOverlayStack.d.ts.map

package/dist/useOverlayStack.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useOverlayStack.d.ts","sourceRoot":"","sources":["../src/useOverlayStack.ts"],"names":[],"mappings":"AAyBA;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,OAAO,UAAO,GAAG;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAclF"}

package/dist/useOverlayStack.js

@@ -0,0 +1,39 @@
+import { useLayoutEffect, useState, useSyncExternalStore } from "react";
+const BASE_Z_INDEX = 1000;
+const Z_INDEX_STEP = 10;
+// Global stack of open overlays, last opened on top.
+let stack = [];
+const listeners = new Set();
+function subscribe(listener) {
+    listeners.add(listener);
+    return () => {
+        listeners.delete(listener);
+    };
+}
+function getSnapshot() {
+    return stack;
+}
+function setStack(next) {
+    stack = next;
+    listeners.forEach(listener => listener());
+}
+/**
+ * Registers an overlay in a page-wide stack while `enabled`.
+ * `isTop` is true for the last opened overlay only (the one that should react to Escape);
+ * `zIndex` puts every overlay above the ones opened before it.
+ */
+export function useOverlayStack(enabled = true) {
+    const [key] = useState(() => Symbol("overlay"));
+    // Layout effect: the z-index is known before the overlay is painted.
+    useLayoutEffect(() => {
+        if (!enabled)
+            return;
+        setStack([...stack, key]);
+        return () => setStack(stack.filter(k => k !== key));
+    }, [enabled, key]);
+    const current = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+    const index = current.indexOf(key);
+    if (index === -1)
+        return { isTop: false, zIndex: BASE_Z_INDEX };
+    return { isTop: index === current.length - 1, zIndex: BASE_Z_INDEX + index * Z_INDEX_STEP };
+}

package/dist/useScrollLock.d.ts

@@ -0,0 +1,3 @@
+/** Blocks page scrolling while `enabled`, compensating the scrollbar width to avoid a layout shift. */
+export declare function useScrollLock(enabled?: boolean): void;
+//# sourceMappingURL=useScrollLock.d.ts.map

package/dist/useScrollLock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useScrollLock.d.ts","sourceRoot":"","sources":["../src/useScrollLock.ts"],"names":[],"mappings":"AAOA,uGAAuG;AACvG,wBAAgB,aAAa,CAAC,OAAO,UAAO,GAAG,IAAI,CAsBlD"}

package/dist/useScrollLock.js

@@ -0,0 +1,29 @@
+import { useEffect } from "react";
+// Reference count: nested locks only release the page when the last one goes away,
+// whatever the order they are released in.
+let lockCount = 0;
+let saved = null;
+/** Blocks page scrolling while `enabled`, compensating the scrollbar width to avoid a layout shift. */
+export function useScrollLock(enabled = true) {
+    useEffect(() => {
+        if (!enabled)
+            return;
+        const body = document.body;
+        if (lockCount === 0) {
+            saved = { overflow: body.style.overflow, paddingRight: body.style.paddingRight };
+            const scrollbarWidth = window.innerWidth - document.documentElement.clientWidth;
+            if (scrollbarWidth > 0)
+                body.style.paddingRight = `${scrollbarWidth}px`;
+            body.style.overflow = "hidden";
+        }
+        lockCount++;
+        return () => {
+            lockCount--;
+            if (lockCount === 0 && saved) {
+                body.style.overflow = saved.overflow;
+                body.style.paddingRight = saved.paddingRight;
+                saved = null;
+            }
+        };
+    }, [enabled]);
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@-reddacted-/react-hooks",
-  "version": "0.1.0",
-  "description": "useFullscreen, useInstallPrompt, useValueChange React hooks",
+  "version": "0.3.0",
+  "description": "React hooks: useAsync, useElementSize, useClickOutside, useEscapeKey, useDocumentTitle, useFullscreen, useInstallPrompt, useValueChange, useFocusTrap, useScrollLock, useOverlayStack",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -11,15 +11,18 @@
       "types": "./dist/index.d.ts"
     }
   },
-  "files": ["dist"],
+  "files": [
+    "dist"
+  ],
   "scripts": {
-    "build": "tsc"
+    "build": "tsc",
+    "typecheck": "tsc --noEmit"
   },
   "peerDependencies": {
     "react": ">=18"
   },
   "devDependencies": {
-    "@types/react": "^19.0.0",
+    "@types/react": "^18.3.1",
     "typescript": "~5.8.3"
   }
 }