@-reddacted-/react-hooks 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -6,4 +6,7 @@ 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,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"}
+{"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

@@ -6,3 +6,6 @@ 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/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.2.0",
-  "description": "React hooks: useAsync, useElementSize, useClickOutside, useEscapeKey, useDocumentTitle, useFullscreen, useInstallPrompt, useValueChange",
+  "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",