preact-missing-hooks 4.4.0 → 4.6.0

package/dist/react.js

@@ -1776,6 +1776,314 @@ function useRefPrint(printRef, options = {}) {
     return { print };
 }
 
+const WILDCARD = "*";
+function parseUserFromStorage(type, key) {
+    if (typeof window === "undefined")
+        return null;
+    const storage = type === "localStorage" ? window.localStorage : window.sessionStorage;
+    try {
+        const raw = storage.getItem(key);
+        if (raw == null)
+            return null;
+        const data = JSON.parse(raw);
+        return data && typeof data === "object" ? data : null;
+    }
+    catch (_a) {
+        return null;
+    }
+}
+function parseCapabilitiesFromStorage(type, key) {
+    if (typeof window === "undefined")
+        return [];
+    const storage = type === "localStorage" ? window.localStorage : window.sessionStorage;
+    try {
+        const raw = storage.getItem(key);
+        if (raw == null)
+            return [];
+        const data = JSON.parse(raw);
+        return Array.isArray(data)
+            ? data.filter((x) => typeof x === "string")
+            : [];
+    }
+    catch (_a) {
+        return [];
+    }
+}
+function computeRoles(user, roleDefinitions) {
+    return roleDefinitions
+        .filter((def) => def.condition(user))
+        .map((def) => def.role);
+}
+function computeCapabilitiesFromRoles(roles, roleCapabilities) {
+    const set = new Set();
+    for (const role of roles) {
+        const caps = roleCapabilities[role];
+        if (Array.isArray(caps)) {
+            for (const c of caps)
+                set.add(c);
+        }
+    }
+    return Array.from(set);
+}
+function hasCapabilityImpl(capabilities, capability) {
+    if (capabilities.includes(WILDCARD))
+        return true;
+    return capabilities.includes(capability);
+}
+/**
+ * Frontend-only role-based access control hook. Define roles with conditions,
+ * assign capabilities per role, and plug in user source (localStorage, sessionStorage, API, or custom).
+ * Supports full flexibility: frontend-only with storage or pluggable API.
+ *
+ * @param options - userSource, roleDefinitions, roleCapabilities, optional capabilitiesOverride
+ * @returns user, roles, capabilities, hasRole, hasCapability, can, isReady, error, refetch, and storage helpers
+ *
+ * @example
+ * ```tsx
+ * const { hasRole, can, roles, setUserInStorage } = useRBAC({
+ *   userSource: { type: 'localStorage', key: 'user' },
+ *   roleDefinitions: [
+ *     { role: 'admin', condition: (u) => u?.role === 'admin' },
+ *     { role: 'editor', condition: (u) => u?.role === 'editor' || u?.role === 'admin' },
+ *   ],
+ *   roleCapabilities: {
+ *     admin: ['*'],
+ *     editor: ['posts:edit', 'posts:create'],
+ *   },
+ * });
+ * if (can('posts:edit')) { ... }
+ * ```
+ */
+function useRBAC(options) {
+    const { userSource } = options;
+    const optsRef = react.useRef(options);
+    optsRef.current = options;
+    const [user, setUser] = react.useState(null);
+    const [roles, setRoles] = react.useState([]);
+    const [capabilities, setCapabilities] = react.useState([]);
+    const [isReady, setIsReady] = react.useState(false);
+    const [error, setError] = react.useState(null);
+    const resolveAuth = react.useCallback(() => __awaiter(this, void 0, void 0, function* () {
+        var _a, _b, _c;
+        const { userSource: us, roleDefinitions: rdefs, roleCapabilities: rcaps, capabilitiesOverride: capOver, } = optsRef.current;
+        setError(null);
+        let resolvedUser = null;
+        let resolvedRoles = [];
+        let resolvedCapabilities = [];
+        try {
+            if (us.type === "localStorage") {
+                resolvedUser = parseUserFromStorage("localStorage", us.key);
+                resolvedRoles = computeRoles(resolvedUser, rdefs);
+                resolvedCapabilities = computeCapabilitiesFromRoles(resolvedRoles, rcaps);
+            }
+            else if (us.type === "sessionStorage") {
+                resolvedUser = parseUserFromStorage("sessionStorage", us.key);
+                resolvedRoles = computeRoles(resolvedUser, rdefs);
+                resolvedCapabilities = computeCapabilitiesFromRoles(resolvedRoles, rcaps);
+            }
+            else if (us.type === "api") {
+                resolvedUser = yield us.fetch();
+                resolvedRoles = computeRoles(resolvedUser, rdefs);
+                resolvedCapabilities = computeCapabilitiesFromRoles(resolvedRoles, rcaps);
+            }
+            else if (us.type === "memory") {
+                resolvedUser = us.getUser();
+                resolvedRoles = computeRoles(resolvedUser, rdefs);
+                resolvedCapabilities = computeCapabilitiesFromRoles(resolvedRoles, rcaps);
+            }
+            else if (us.type === "custom") {
+                const auth = yield Promise.resolve(us.getAuth());
+                resolvedUser = (_a = auth.user) !== null && _a !== void 0 ? _a : null;
+                resolvedRoles = (_b = auth.roles) !== null && _b !== void 0 ? _b : computeRoles(resolvedUser, rdefs);
+                resolvedCapabilities =
+                    (_c = auth.capabilities) !== null && _c !== void 0 ? _c : computeCapabilitiesFromRoles(resolvedRoles, rcaps);
+            }
+            if (capOver) {
+                if (capOver.type === "localStorage") {
+                    const override = parseCapabilitiesFromStorage("localStorage", capOver.key);
+                    if (override.length > 0)
+                        resolvedCapabilities = override;
+                }
+                else if (capOver.type === "sessionStorage") {
+                    const override = parseCapabilitiesFromStorage("sessionStorage", capOver.key);
+                    if (override.length > 0)
+                        resolvedCapabilities = override;
+                }
+                else if (capOver.type === "api") {
+                    const override = yield capOver.fetch();
+                    resolvedCapabilities = override;
+                }
+            }
+            setUser(resolvedUser);
+            setRoles(resolvedRoles);
+            setCapabilities(resolvedCapabilities);
+        }
+        catch (e) {
+            setError(e instanceof Error ? e : new Error(String(e)));
+            setUser(null);
+            setRoles([]);
+            setCapabilities([]);
+        }
+        finally {
+            setIsReady(true);
+        }
+    }), []);
+    react.useEffect(() => {
+        resolveAuth();
+    }, [resolveAuth]);
+    // Listen to storage events when using localStorage/sessionStorage so we refetch when another tab changes data
+    react.useEffect(() => {
+        if (typeof window === "undefined")
+            return;
+        const key = userSource.type === "localStorage" || userSource.type === "sessionStorage"
+            ? userSource.key
+            : null;
+        if (!key)
+            return;
+        const handler = (e) => {
+            if (e.key === key)
+                void resolveAuth();
+        };
+        window.addEventListener("storage", handler);
+        return () => window.removeEventListener("storage", handler);
+    }, [
+        userSource.type,
+        userSource.type === "localStorage" || userSource.type === "sessionStorage"
+            ? userSource.key
+            : "",
+        resolveAuth,
+    ]);
+    const hasRole = react.useCallback((role) => roles.includes(role), [roles]);
+    const hasCapability = react.useCallback((capability) => hasCapabilityImpl(capabilities, capability), [capabilities]);
+    const can = hasCapability;
+    const refetch = react.useCallback(() => resolveAuth(), [resolveAuth]);
+    const setUserInStorage = react.useCallback((newUser, storage, key) => {
+        if (typeof window === "undefined")
+            return;
+        const s = storage === "localStorage"
+            ? window.localStorage
+            : window.sessionStorage;
+        if (newUser == null)
+            s.removeItem(key);
+        else
+            s.setItem(key, JSON.stringify(newUser));
+        if ((userSource.type === "localStorage" &&
+            storage === "localStorage" &&
+            userSource.key === key) ||
+            (userSource.type === "sessionStorage" &&
+                storage === "sessionStorage" &&
+                userSource.key === key)) {
+            void resolveAuth();
+        }
+    }, [userSource, resolveAuth]);
+    const setRolesInStorage = react.useCallback((newRoles, storage, key) => {
+        if (typeof window === "undefined")
+            return;
+        const s = storage === "localStorage"
+            ? window.localStorage
+            : window.sessionStorage;
+        s.setItem(key, JSON.stringify(newRoles));
+    }, []);
+    const setCapabilitiesInStorage = react.useCallback((newCaps, storage, key) => {
+        if (typeof window === "undefined")
+            return;
+        const s = storage === "localStorage"
+            ? window.localStorage
+            : window.sessionStorage;
+        s.setItem(key, JSON.stringify(newCaps));
+    }, []);
+    return {
+        user,
+        roles,
+        capabilities,
+        isReady,
+        error,
+        hasRole,
+        hasCapability,
+        can,
+        refetch,
+        setUserInStorage,
+        setRolesInStorage,
+        setCapabilitiesInStorage,
+    };
+}
+
+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 };
+}
+
 exports.useClipboard = useClipboard;
 exports.useEventBus = useEventBus;
 exports.useIndexedDB = useIndexedDB;
@@ -1783,6 +2091,8 @@ exports.useLLMMetadata = useLLMMetadata;
 exports.useMutationObserver = useMutationObserver;
 exports.useNetworkState = useNetworkState;
 exports.usePreferredTheme = usePreferredTheme;
+exports.usePrefetch = usePrefetch;
+exports.useRBAC = useRBAC;
 exports.useRageClick = useRageClick;
 exports.useRefPrint = useRefPrint;
 exports.useThreadedWorker = useThreadedWorker;

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/dist/useRBAC.d.ts

@@ -0,0 +1,102 @@
+/** Flexible user object; your app can use any shape. */
+export type RBACUser = Record<string, unknown>;
+/** Get auth state (user + optional roles/capabilities). Used by custom source. */
+export interface RBACAuthState {
+    user?: RBACUser | null;
+    roles?: string[];
+    capabilities?: string[];
+}
+/** Pluggable source for current user (and optionally roles/capabilities). */
+export type RBACUserSource = {
+    type: "localStorage";
+    key: string;
+} | {
+    type: "sessionStorage";
+    key: string;
+} | {
+    type: "api";
+    fetch: () => Promise<RBACUser>;
+} | {
+    type: "memory";
+    getUser: () => RBACUser | null;
+} | {
+    type: "custom";
+    getAuth: () => RBACAuthState | Promise<RBACAuthState>;
+};
+/** Role definition: name + condition to grant this role based on user. */
+export interface RBACRoleDefinition {
+    role: string;
+    condition: (user: RBACUser | null) => boolean;
+}
+/** Role name -> list of capability strings. Use '*' for full access. */
+export type RBACRoleCapabilities = Record<string, string[]>;
+/** Optional override: get capabilities directly (e.g. from API) instead of deriving from roles. */
+export type RBACCapabilitiesOverride = {
+    type: "localStorage";
+    key: string;
+} | {
+    type: "sessionStorage";
+    key: string;
+} | {
+    type: "api";
+    fetch: () => Promise<string[]>;
+};
+export interface UseRBACOptions {
+    /** Where to get the current user (and optionally roles/capabilities if type is 'custom'). */
+    userSource: RBACUserSource;
+    /** Role definitions: each role has a condition(user) to determine if the user has that role. */
+    roleDefinitions: RBACRoleDefinition[];
+    /** Capabilities per role. User gets union of capabilities for all their roles. Use '*' for admin. */
+    roleCapabilities: RBACRoleCapabilities;
+    /** Optional: fetch capabilities directly (overrides role-derived capabilities when provided). */
+    capabilitiesOverride?: RBACCapabilitiesOverride;
+}
+export interface UseRBACReturn {
+    /** Current user from source, or null. */
+    user: RBACUser | null;
+    /** Resolved roles for the current user. */
+    roles: string[];
+    /** Resolved capabilities (union of role capabilities, or from override). */
+    capabilities: string[];
+    /** True when user/roles/capabilities have been resolved (or failed). */
+    isReady: boolean;
+    /** Error from source (e.g. API or parse). */
+    error: Error | null;
+    /** Check if the user has the given role. */
+    hasRole: (role: string) => boolean;
+    /** Check if the user has the given capability (or '*' ). */
+    hasCapability: (capability: string) => boolean;
+    /** Alias for hasCapability. */
+    can: (capability: string) => boolean;
+    /** Re-fetch user/roles/capabilities from source. */
+    refetch: () => Promise<void>;
+    /** Helpers to persist auth to storage (for frontend-only flows). */
+    setUserInStorage: (user: RBACUser | null, storage: "localStorage" | "sessionStorage", key: string) => void;
+    setRolesInStorage: (roles: string[], storage: "localStorage" | "sessionStorage", key: string) => void;
+    setCapabilitiesInStorage: (capabilities: string[], storage: "localStorage" | "sessionStorage", key: string) => void;
+}
+/**
+ * Frontend-only role-based access control hook. Define roles with conditions,
+ * assign capabilities per role, and plug in user source (localStorage, sessionStorage, API, or custom).
+ * Supports full flexibility: frontend-only with storage or pluggable API.
+ *
+ * @param options - userSource, roleDefinitions, roleCapabilities, optional capabilitiesOverride
+ * @returns user, roles, capabilities, hasRole, hasCapability, can, isReady, error, refetch, and storage helpers
+ *
+ * @example
+ * ```tsx
+ * const { hasRole, can, roles, setUserInStorage } = useRBAC({
+ *   userSource: { type: 'localStorage', key: 'user' },
+ *   roleDefinitions: [
+ *     { role: 'admin', condition: (u) => u?.role === 'admin' },
+ *     { role: 'editor', condition: (u) => u?.role === 'editor' || u?.role === 'admin' },
+ *   ],
+ *   roleCapabilities: {
+ *     admin: ['*'],
+ *     editor: ['posts:edit', 'posts:create'],
+ *   },
+ * });
+ * if (can('posts:edit')) { ... }
+ * ```
+ */
+export declare function useRBAC(options: UseRBACOptions): UseRBACReturn;

package/docs/README.md

@@ -41,6 +41,7 @@ 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.                                                                                                                          |
 | **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 +49,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 +91,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/index.html

@@ -323,6 +323,56 @@
           transform: translateX(0);
         }
       }
+      /* useRBAC demo */
+      .rbac-demo {
+        display: flex;
+        flex-direction: column;
+        gap: 0.75rem;
+      }
+      .rbac-toolbar {
+        display: flex;
+        align-items: center;
+        flex-wrap: wrap;
+        gap: 0.25rem;
+      }
+      .rbac-toolbar button {
+        padding: 0.25rem 0.5rem;
+        font-size: 0.8rem;
+        cursor: pointer;
+        background: var(--surface2);
+        border: 1px solid var(--border);
+        border-radius: var(--radiusSm);
+        color: var(--text);
+      }
+      .rbac-toolbar button:hover {
+        background: var(--border);
+      }
+      .rbac-actions {
+        display: flex;
+        flex-wrap: wrap;
+        gap: 0.35rem;
+      }
+      .rbac-state {
+        background: var(--surface2);
+        border-radius: var(--radiusSm);
+        padding: 0.6rem 0.75rem;
+        font-size: 0.85rem;
+      }
+      .rbac-state-row {
+        margin-bottom: 0.35rem;
+      }
+      .rbac-state-row:last-child {
+        margin-bottom: 0;
+      }
+      .rbac-state-row code {
+        margin-left: 0.25rem;
+      }
+      .rbac-conditional {
+        display: flex;
+        flex-wrap: wrap;
+        align-items: center;
+        gap: 0.25rem;
+      }
     </style>
   </head>
   <body>