preact-missing-hooks 4.5.0 → 4.7.0

package/dist/react.js

@@ -2008,13 +2008,168 @@ function useRBAC(options) {
     };
 }
 
+function prefetchDocument(url) {
+    if (typeof document === "undefined")
+        return;
+    const links = document.querySelectorAll('link[rel="prefetch"]');
+    for (let i = 0; i < links.length; i++) {
+        if (links[i].href === url)
+            return;
+    }
+    const link = document.createElement("link");
+    link.rel = "prefetch";
+    link.href = url;
+    document.head.appendChild(link);
+}
+function prefetchFetch(url) {
+    if (typeof fetch === "undefined")
+        return;
+    fetch(url, { method: "GET", mode: "cors" }).catch(() => {
+        /* ignore; prefetch is best-effort */
+    });
+}
+/**
+ * A Preact hook that returns a stable prefetch function to preload URLs (documents or data)
+ * so they are cached before the user navigates or needs them. Useful for link hover or
+ * route preloading.
+ *
+ * @returns Object with prefetch(url, options?) and isPrefetched(url)
+ *
+ * @example
+ * ```tsx
+ * function NavLink({ href, children }) {
+ *   const { prefetch } = usePrefetch();
+ *   return (
+ *     <a
+ *       href={href}
+ *       onMouseEnter={() => prefetch(href)}
+ *     >
+ *       {children}
+ *     </a>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Prefetch API data
+ * const { prefetch } = usePrefetch();
+ * prefetch('/api/user', { as: 'fetch' });
+ * ```
+ */
+function usePrefetch() {
+    const prefetchedRef = react.useRef(new Set());
+    const [, setTick] = react.useState(0);
+    const prefetch = react.useCallback((url, options) => {
+        var _a;
+        const trimmed = url === null || url === void 0 ? void 0 : url.trim();
+        if (!trimmed)
+            return;
+        if (prefetchedRef.current.has(trimmed))
+            return;
+        const as = (_a = options === null || options === void 0 ? void 0 : options.as) !== null && _a !== void 0 ? _a : "document";
+        if (as === "document") {
+            prefetchDocument(trimmed);
+        }
+        else {
+            prefetchFetch(trimmed);
+        }
+        prefetchedRef.current.add(trimmed);
+        setTick((n) => n + 1);
+    }, []);
+    const isPrefetched = react.useCallback((url) => {
+        var _a;
+        return prefetchedRef.current.has((_a = url === null || url === void 0 ? void 0 : url.trim()) !== null && _a !== void 0 ? _a : "");
+    }, []);
+    return { prefetch, isPrefetched };
+}
+
+/**
+ * Polls an async function at a fixed interval until it returns { done: true, data? }.
+ * Useful for waiting on a backend job, readiness checks, or until a condition is met.
+ *
+ * @param pollFn - Async function called each tick. Return { done: true, data? } to stop and set result.
+ * @param options - intervalMs, immediate, enabled
+ * @returns { data, done, error, pollCount, start, stop }
+ *
+ * @example
+ * ```tsx
+ * const { data, done, pollCount } = usePoll(
+ *   async () => {
+ *     const res = await fetch('/api/status');
+ *     const json = await res.json();
+ *     return json.ready ? { done: true, data: json } : { done: false };
+ *   },
+ *   { intervalMs: 500, immediate: true }
+ * );
+ * return done ? <div>Ready: {JSON.stringify(data)}</div> : <div>Polling… ({pollCount})</div>;
+ * ```
+ */
+function usePoll(pollFn, options = {}) {
+    const { intervalMs = 1000, immediate = true, enabled = true } = options;
+    const [data, setData] = react.useState(null);
+    const [done, setDone] = react.useState(false);
+    const [error, setError] = react.useState(null);
+    const [pollCount, setPollCount] = react.useState(0);
+    const [running, setRunning] = react.useState(false);
+    const intervalRef = react.useRef(null);
+    const pollFnRef = react.useRef(pollFn);
+    pollFnRef.current = pollFn;
+    const stop = react.useCallback(() => {
+        if (intervalRef.current != null) {
+            clearInterval(intervalRef.current);
+            intervalRef.current = null;
+        }
+        setRunning(false);
+    }, []);
+    const tick = react.useCallback(() => __awaiter(this, void 0, void 0, function* () {
+        try {
+            setError(null);
+            const result = yield pollFnRef.current();
+            setPollCount((n) => n + 1);
+            if (result.done) {
+                stop();
+                setDone(true);
+                if (result.data !== undefined) {
+                    setData(result.data);
+                }
+            }
+        }
+        catch (e) {
+            const err = e instanceof Error ? e : new Error(String(e));
+            setError(err);
+            stop();
+        }
+    }), [stop]);
+    const start = react.useCallback(() => {
+        if (!enabled || running)
+            return;
+        setRunning(true);
+        if (immediate) {
+            tick();
+        }
+        intervalRef.current = setInterval(tick, intervalMs);
+    }, [enabled, immediate, intervalMs, running, tick]);
+    react.useEffect(() => {
+        if (enabled) {
+            start();
+        }
+        return () => {
+            stop();
+        };
+    }, [enabled]);
+    return { data, done, error, pollCount, start, stop };
+}
+
 exports.useClipboard = useClipboard;
 exports.useEventBus = useEventBus;
 exports.useIndexedDB = useIndexedDB;
 exports.useLLMMetadata = useLLMMetadata;
 exports.useMutationObserver = useMutationObserver;
 exports.useNetworkState = useNetworkState;
+exports.usePoll = usePoll;
 exports.usePreferredTheme = usePreferredTheme;
+exports.usePrefetch = usePrefetch;
 exports.useRBAC = useRBAC;
 exports.useRageClick = useRageClick;
 exports.useRefPrint = useRefPrint;

package/dist/usePoll.d.ts

@@ -0,0 +1,47 @@
+export interface UsePollOptions {
+    /** Polling interval in milliseconds. Default: 1000 */
+    intervalMs?: number;
+    /** Run the poll function immediately when the hook mounts. Default: true */
+    immediate?: boolean;
+    /** When false, do not start or continue polling. Default: true */
+    enabled?: boolean;
+}
+export interface UsePollResult<T> {
+    /** Last resolved data when poll returned done: true */
+    data: T | null;
+    /** True once the poll function returned { done: true } */
+    done: boolean;
+    /** Error from the last failed poll call */
+    error: Error | null;
+    /** Number of times the poll function has been invoked */
+    pollCount: number;
+    /** Manually start polling (e.g. after reset). Only has effect when not already polling. */
+    start: () => void;
+    /** Stop polling. */
+    stop: () => void;
+}
+/**
+ * Polls an async function at a fixed interval until it returns { done: true, data? }.
+ * Useful for waiting on a backend job, readiness checks, or until a condition is met.
+ *
+ * @param pollFn - Async function called each tick. Return { done: true, data? } to stop and set result.
+ * @param options - intervalMs, immediate, enabled
+ * @returns { data, done, error, pollCount, start, stop }
+ *
+ * @example
+ * ```tsx
+ * const { data, done, pollCount } = usePoll(
+ *   async () => {
+ *     const res = await fetch('/api/status');
+ *     const json = await res.json();
+ *     return json.ready ? { done: true, data: json } : { done: false };
+ *   },
+ *   { intervalMs: 500, immediate: true }
+ * );
+ * return done ? <div>Ready: {JSON.stringify(data)}</div> : <div>Polling… ({pollCount})</div>;
+ * ```
+ */
+export declare function usePoll<T>(pollFn: () => Promise<{
+    done: boolean;
+    data?: T;
+}>, options?: UsePollOptions): UsePollResult<T>;

package/dist/usePrefetch.d.ts

@@ -0,0 +1,44 @@
+export interface UsePrefetchOptions {
+    /**
+     * Resource type for prefetch.
+     * - "document": uses <link rel="prefetch"> (default, for next navigation)
+     * - "fetch": uses fetch() to warm the HTTP cache (e.g. for API or same-origin data)
+     */
+    as?: "document" | "fetch";
+}
+export interface UsePrefetchReturn {
+    /** Prefetch a URL so it is cached for later use. No-op if URL was already prefetched or empty. */
+    prefetch: (url: string, options?: UsePrefetchOptions) => void;
+    /** Check whether a URL has already been prefetched in this hook instance. */
+    isPrefetched: (url: string) => boolean;
+}
+/**
+ * A Preact hook that returns a stable prefetch function to preload URLs (documents or data)
+ * so they are cached before the user navigates or needs them. Useful for link hover or
+ * route preloading.
+ *
+ * @returns Object with prefetch(url, options?) and isPrefetched(url)
+ *
+ * @example
+ * ```tsx
+ * function NavLink({ href, children }) {
+ *   const { prefetch } = usePrefetch();
+ *   return (
+ *     <a
+ *       href={href}
+ *       onMouseEnter={() => prefetch(href)}
+ *     >
+ *       {children}
+ *     </a>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Prefetch API data
+ * const { prefetch } = usePrefetch();
+ * prefetch('/api/user', { as: 'fetch' });
+ * ```
+ */
+export declare function usePrefetch(): UsePrefetchReturn;

package/docs/README.md

@@ -41,6 +41,8 @@ Open `docs/index.html` in a browser that supports ES modules and import maps. Th
 | **useWrappedChildren**     | Children buttons get injected styles.                                                                                                                                                                 |
 | **usePreferredTheme**      | Shows light / dark / no-preference from system.                                                                                                                                                       |
 | **useNetworkState**        | Online/offline and connection type.                                                                                                                                                                   |
+| **usePrefetch**            | Hover or click to prefetch a URL (document or fetch); see prefetched status.                                                                                                                          |
+| **usePoll**                | Poll until done (3 ticks); see poll count and result. Stop button to cancel.                                                                                                                          |
 | **useClipboard**           | Copy and paste; see “Copied!” and pasted text.                                                                                                                                                        |
 | **useRageClick**           | Click the area 3+ times quickly; rage click count.                                                                                                                                                    |
 | **useThreadedWorker**      | Run a task; see loading and result.                                                                                                                                                                   |
@@ -48,6 +50,8 @@ Open `docs/index.html` in a browser that supports ES modules and import maps. Th
 | **useWebRTCIP**            | Detect IP via WebRTC (may take a few seconds).                                                                                                                                                        |
 | **useWasmCompute**         | Run WASM in a worker (needs `add.wasm` in docs).                                                                                                                                                      |
 | **useWorkerNotifications** | Run/fail tasks and queue updates; toasts show events.                                                                                                                                                 |
+| **useRefPrint**            | Bind a ref to a section and click “Print / Save as PDF”; only that section is printed via `@media print`.                                                                                             |
+| **useRBAC**                | Login as Admin / Editor / Viewer (localStorage or sessionStorage); see roles and capabilities; conditional UI by `can(...)`.                                                                          |
 | **useLLMMetadata**         | Change “route” with buttons; see injected script info in the Live panel and `<script data-llm="true">` in the document head. Safe with `null`/`undefined` config (minimal payload with `route: "/"`). |
 
 ---
@@ -88,6 +92,110 @@ function App() {
 }
 ```
 
+### useRefPrint example
+
+Print only a specific section via the native print dialog (user can save as PDF):
+
+```js
+import { h, render } from "preact";
+import { useRef } from "preact/hooks";
+import { useRefPrint } from "preact-missing-hooks";
+
+function Report() {
+  const printRef = useRef(null);
+  const { print } = useRefPrint(printRef, {
+    documentTitle: "My Report",
+    downloadAsPdf: true,
+  });
+  return h(
+    "div",
+    {},
+    h(
+      "div",
+      { ref: printRef, style: { padding: "1rem", background: "#f5f5f5" } },
+      "Only this section is printed when you click the button."
+    ),
+    h("button", { onClick: print }, "Print / Save as PDF")
+  );
+}
+render(h(Report), document.getElementById("root"));
+```
+
+### useRBAC example
+
+Frontend-only role-based access: define roles with conditions, assign capabilities per role, and read the current user from localStorage (or sessionStorage / API):
+
+```js
+import { h, render } from "preact";
+import { useRBAC } from "preact-missing-hooks";
+
+const roleDefinitions = [
+  { role: "admin", condition: (u) => u && u.role === "admin" },
+  {
+    role: "editor",
+    condition: (u) => u && (u.role === "editor" || u.role === "admin"),
+  },
+  { role: "viewer", condition: (u) => u && u.id != null },
+];
+const roleCapabilities = {
+  admin: ["*"],
+  editor: ["posts:edit", "posts:create", "posts:read"],
+  viewer: ["posts:read"],
+};
+
+function App() {
+  const { user, roles, can, setUserInStorage } = useRBAC({
+    userSource: { type: "localStorage", key: "app-user" },
+    roleDefinitions,
+    roleCapabilities,
+  });
+
+  if (!user) {
+    return h(
+      "div",
+      {},
+      h(
+        "button",
+        {
+          onClick: () =>
+            setUserInStorage(
+              { id: 1, role: "admin" },
+              "localStorage",
+              "app-user"
+            ),
+        },
+        "Login as Admin"
+      ),
+      h(
+        "button",
+        {
+          onClick: () =>
+            setUserInStorage(
+              { id: 2, role: "viewer" },
+              "localStorage",
+              "app-user"
+            ),
+        },
+        "Login as Viewer"
+      )
+    );
+  }
+  return h(
+    "div",
+    {},
+    h("p", {}, "Roles: " + roles.join(", ")),
+    can("posts:edit") && h("button", {}, "Edit post"),
+    can("*") && h("button", {}, "Admin panel"),
+    h(
+      "button",
+      { onClick: () => setUserInStorage(null, "localStorage", "app-user") },
+      "Logout"
+    )
+  );
+}
+render(h(App), document.getElementById("root"));
+```
+
 ### useLLMMetadata in the demo
 
 The **useLLMMetadata** Live panel simulates route changes. Click “Route: /”, “Route: /blog”, or “Route: /docs”. Each change:

package/docs/main.js

@@ -21,6 +21,8 @@ const {
   useLLMMetadata,
   useRefPrint,
   useRBAC,
+  usePrefetch,
+  usePoll,
 } = await import(
   isLocal ? '../dist/index.module.js' : 'https://unpkg.com/preact-missing-hooks/dist/index.module.js'
 );
@@ -84,6 +86,55 @@ function DemoNetworkState() {
   );
 }
 
+function DemoPrefetch() {
+  const { prefetch, isPrefetched } = usePrefetch();
+  const [lastUrl, setLastUrl] = useState('');
+  const demoUrl = 'https://example.com/prefetched-page';
+  const fetchUrl = 'https://httpbin.org/get';
+  const doPrefetchDoc = () => { prefetch(demoUrl); setLastUrl(demoUrl); };
+  const doPrefetchFetch = () => { prefetch(fetchUrl, { as: 'fetch' }); setLastUrl(fetchUrl); };
+  return h('div', {},
+    h('div', { style: { marginBottom: '0.5rem', fontSize: '0.85rem' } }, [
+      h('button', {
+        onClick: doPrefetchDoc,
+        onMouseEnter: doPrefetchDoc,
+      }, 'Prefetch document'),
+      ' ',
+      h('button', {
+        onClick: doPrefetchFetch,
+        onMouseEnter: doPrefetchFetch,
+      }, 'Prefetch (fetch)'),
+    ]),
+    lastUrl
+      ? h('span', { class: 'badge green', style: { marginLeft: '0.35rem' } },
+        'Prefetched: ' + lastUrl + (isPrefetched(lastUrl) ? ' ✓' : ''))
+      : h('span', { class: 'status' }, 'Hover or click to prefetch a URL (document or fetch).')
+  );
+}
+
+function DemoPoll() {
+  const countRef = { current: 0 };
+  const { data, done, error, pollCount, start, stop } = usePoll(
+    async () => {
+      countRef.current += 1;
+      if (countRef.current >= 3) return { done: true, data: { message: 'Ready after ' + countRef.current + ' polls' } };
+      return { done: false };
+    },
+    { intervalMs: 700, immediate: true }
+  );
+  return h('div', {},
+    h('div', { style: { marginBottom: '0.5rem', fontSize: '0.85rem' } }, [
+      h('button', { onClick: start }, 'Start'),
+      ' ',
+      h('button', { onClick: stop }, 'Stop'),
+    ]),
+    error ? h('span', { class: 'badge', style: { background: 'var(--red)', color: '#fff' } }, error.message) : null,
+    done
+      ? h('span', { class: 'badge green', style: { marginLeft: '0.35rem' } }, data?.message ?? 'Done')
+      : h('span', { class: 'status' }, 'Polling… (' + pollCount + ' calls)')
+  );
+}
+
 function DemoClipboard() {
   const { copy, paste, copied, error } = useClipboard();
   const [pasted, setPasted] = useState('');
@@ -511,6 +562,20 @@ const HOOKS = [
     code: `const state = useNetworkState();\n// state.online, state.effectiveType, ...`,
     Live: DemoNetworkState,
   },
+  {
+    name: 'usePrefetch',
+    flow: 'Component → usePrefetch() → prefetch(url, options?) → link rel=prefetch or fetch()',
+    summary: 'Preload URLs (documents or data) so they are cached before navigation or use. Ideal for link hover or route preloading.',
+    code: `const { prefetch, isPrefetched } = usePrefetch();\n<a onMouseEnter={() => prefetch(href)} href={href}>Link</a>\n// or prefetch(url, { as: 'fetch' }) for API`,
+    Live: DemoPrefetch,
+  },
+  {
+    name: 'usePoll',
+    flow: 'Component → usePoll(pollFn, { intervalMs, immediate }) → poll until done: true → data, done, pollCount',
+    summary: 'Polls an async function at a fixed interval until it returns { done: true, data? }. Stops on error. Good for readiness checks or waiting on a backend job.',
+    code: `const { data, done, error, pollCount, stop } = usePoll(\n  async () => (await fetch('/api/status')).ok ? { done: true, data } : { done: false },\n  { intervalMs: 1000, immediate: true }\n);`,
+    Live: DemoPoll,
+  },
   {
     name: 'useClipboard',
     flow: 'Component → useClipboard() → copy(text) / paste() → Clipboard API',