@-reddacted-/react-hooks 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -1,5 +1,9 @@
-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";
 //# 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"}

package/dist/index.js

@@ -1,3 +1,8 @@
-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";

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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@-reddacted-/react-hooks",
-  "version": "0.1.0",
-  "description": "useFullscreen, useInstallPrompt, useValueChange React hooks",
+  "version": "0.2.0",
+  "description": "React hooks: useAsync, useElementSize, useClickOutside, useEscapeKey, useDocumentTitle, useFullscreen, useInstallPrompt, useValueChange",
   "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"
   }
 }