preact-missing-hooks 4.6.0 → 4.8.0

package/dist/react.js

@@ -2084,12 +2084,282 @@ function usePrefetch() {
     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 };
+}
+
+const SSR_DEVICE_DATA = {
+    userAgent: "",
+    language: "en",
+    languages: ["en"],
+    platform: "",
+    cookieEnabled: false,
+    online: true,
+    maxTouchPoints: 0,
+    vendor: "",
+    touch: false,
+    screen: {
+        width: 0,
+        height: 0,
+        availWidth: 0,
+        availHeight: 0,
+        colorDepth: 24,
+        pixelRatio: 1,
+    },
+    viewport: { width: 0, height: 0 },
+    reducedMotion: false,
+    colorScheme: "no-preference",
+};
+function getColorScheme() {
+    if (typeof window === "undefined" || !window.matchMedia) {
+        return "no-preference";
+    }
+    if (window.matchMedia("(prefers-color-scheme: dark)").matches) {
+        return "dark";
+    }
+    if (window.matchMedia("(prefers-color-scheme: light)").matches) {
+        return "light";
+    }
+    return "no-preference";
+}
+function getReducedMotion() {
+    if (typeof window === "undefined" || !window.matchMedia) {
+        return false;
+    }
+    return window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+}
+/** Reads synchronous device / browser data from Navigator, Screen, and matchMedia. */
+function getDeviceData() {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q;
+    if (typeof navigator === "undefined") {
+        return SSR_DEVICE_DATA;
+    }
+    const nav = navigator;
+    const screen = typeof globalThis.screen !== "undefined" ? globalThis.screen : null;
+    const win = typeof globalThis.window !== "undefined" ? globalThis.window : null;
+    const data = {
+        userAgent: (_a = nav.userAgent) !== null && _a !== void 0 ? _a : "",
+        language: (_b = nav.language) !== null && _b !== void 0 ? _b : "",
+        languages: nav.languages ? [...nav.languages] : [],
+        platform: (_c = nav.platform) !== null && _c !== void 0 ? _c : "",
+        cookieEnabled: Boolean(nav.cookieEnabled),
+        online: Boolean(nav.onLine),
+        maxTouchPoints: (_d = nav.maxTouchPoints) !== null && _d !== void 0 ? _d : 0,
+        vendor: (_e = nav.vendor) !== null && _e !== void 0 ? _e : "",
+        touch: ((_f = nav.maxTouchPoints) !== null && _f !== void 0 ? _f : 0) > 0,
+        screen: {
+            width: (_g = screen === null || screen === void 0 ? void 0 : screen.width) !== null && _g !== void 0 ? _g : 0,
+            height: (_h = screen === null || screen === void 0 ? void 0 : screen.height) !== null && _h !== void 0 ? _h : 0,
+            availWidth: (_j = screen === null || screen === void 0 ? void 0 : screen.availWidth) !== null && _j !== void 0 ? _j : 0,
+            availHeight: (_k = screen === null || screen === void 0 ? void 0 : screen.availHeight) !== null && _k !== void 0 ? _k : 0,
+            colorDepth: (_l = screen === null || screen === void 0 ? void 0 : screen.colorDepth) !== null && _l !== void 0 ? _l : 24,
+            pixelRatio: (_m = win === null || win === void 0 ? void 0 : win.devicePixelRatio) !== null && _m !== void 0 ? _m : 1,
+        },
+        viewport: {
+            width: (_o = win === null || win === void 0 ? void 0 : win.innerWidth) !== null && _o !== void 0 ? _o : 0,
+            height: (_p = win === null || win === void 0 ? void 0 : win.innerHeight) !== null && _p !== void 0 ? _p : 0,
+        },
+        reducedMotion: getReducedMotion(),
+        colorScheme: getColorScheme(),
+    };
+    if (typeof nav.hardwareConcurrency === "number") {
+        data.hardwareConcurrency = nav.hardwareConcurrency;
+    }
+    if (typeof nav.deviceMemory === "number") {
+        data.deviceMemory = nav.deviceMemory;
+    }
+    const uaData = nav.userAgentData;
+    if (uaData) {
+        data.userAgentData = {
+            mobile: Boolean(uaData.mobile),
+            platform: (_q = uaData.platform) !== null && _q !== void 0 ? _q : "",
+            brands: uaData.brands ? [...uaData.brands] : [],
+        };
+    }
+    return data;
+}
+function readBattery() {
+    return __awaiter(this, void 0, void 0, function* () {
+        if (typeof navigator === "undefined")
+            return undefined;
+        const getBattery = navigator.getBattery;
+        if (!getBattery)
+            return undefined;
+        try {
+            const battery = yield getBattery.call(navigator);
+            return { charging: battery.charging, level: battery.level };
+        }
+        catch (_a) {
+            return undefined;
+        }
+    });
+}
+/**
+ * Extracts device and browser data from native Navigator, Screen, window, and
+ * matchMedia APIs. Updates on resize, orientation, online/offline, and
+ * prefers-color-scheme / prefers-reduced-motion changes. Optionally polls the
+ * Battery Status API when available.
+ *
+ * @param options - `includeBattery` (default true), `batteryPollIntervalMs` (default 60000)
+ * @returns Current {@link DeviceData} snapshot
+ *
+ * @example
+ * ```tsx
+ * function DevicePanel() {
+ *   const device = useDeviceData();
+ *   return (
+ *     <dl>
+ *       <dt>Language</dt><dd>{device.language}</dd>
+ *       <dt>CPUs</dt><dd>{device.hardwareConcurrency ?? '—'}</dd>
+ *       <dt>Viewport</dt><dd>{device.viewport.width}×{device.viewport.height}</dd>
+ *       <dt>Theme</dt><dd>{device.colorScheme}</dd>
+ *     </dl>
+ *   );
+ * }
+ * ```
+ */
+function useDeviceData(options = {}) {
+    const { includeBattery = true, batteryPollIntervalMs = 60000 } = options;
+    const [data, setData] = react.useState(() => getDeviceData());
+    const refresh = react.useCallback(() => {
+        setData((prev) => {
+            const next = getDeviceData();
+            return prev.battery ? Object.assign(Object.assign({}, next), { battery: prev.battery }) : next;
+        });
+    }, []);
+    react.useEffect(() => {
+        var _a, _b, _c, _d, _e, _f;
+        if (typeof window === "undefined")
+            return;
+        const onResize = () => refresh();
+        window.addEventListener("resize", onResize);
+        window.addEventListener("orientationchange", onResize);
+        window.addEventListener("online", refresh);
+        window.addEventListener("offline", refresh);
+        const reducedMotionMq = (_a = window.matchMedia) === null || _a === void 0 ? void 0 : _a.call(window, "(prefers-reduced-motion: reduce)");
+        const darkMq = (_b = window.matchMedia) === null || _b === void 0 ? void 0 : _b.call(window, "(prefers-color-scheme: dark)");
+        const lightMq = (_c = window.matchMedia) === null || _c === void 0 ? void 0 : _c.call(window, "(prefers-color-scheme: light)");
+        const onMediaChange = () => refresh();
+        (_d = reducedMotionMq === null || reducedMotionMq === void 0 ? void 0 : reducedMotionMq.addEventListener) === null || _d === void 0 ? void 0 : _d.call(reducedMotionMq, "change", onMediaChange);
+        (_e = darkMq === null || darkMq === void 0 ? void 0 : darkMq.addEventListener) === null || _e === void 0 ? void 0 : _e.call(darkMq, "change", onMediaChange);
+        (_f = lightMq === null || lightMq === void 0 ? void 0 : lightMq.addEventListener) === null || _f === void 0 ? void 0 : _f.call(lightMq, "change", onMediaChange);
+        return () => {
+            var _a, _b, _c;
+            window.removeEventListener("resize", onResize);
+            window.removeEventListener("orientationchange", onResize);
+            window.removeEventListener("online", refresh);
+            window.removeEventListener("offline", refresh);
+            (_a = reducedMotionMq === null || reducedMotionMq === void 0 ? void 0 : reducedMotionMq.removeEventListener) === null || _a === void 0 ? void 0 : _a.call(reducedMotionMq, "change", onMediaChange);
+            (_b = darkMq === null || darkMq === void 0 ? void 0 : darkMq.removeEventListener) === null || _b === void 0 ? void 0 : _b.call(darkMq, "change", onMediaChange);
+            (_c = lightMq === null || lightMq === void 0 ? void 0 : lightMq.removeEventListener) === null || _c === void 0 ? void 0 : _c.call(lightMq, "change", onMediaChange);
+        };
+    }, [refresh]);
+    react.useEffect(() => {
+        if (!includeBattery || typeof navigator === "undefined")
+            return;
+        let cancelled = false;
+        let intervalId;
+        const updateBattery = () => __awaiter(this, void 0, void 0, function* () {
+            const battery = yield readBattery();
+            if (cancelled || battery === undefined)
+                return;
+            setData((prev) => (Object.assign(Object.assign({}, prev), { battery })));
+        });
+        void updateBattery();
+        if (batteryPollIntervalMs > 0) {
+            intervalId = setInterval(() => void updateBattery(), batteryPollIntervalMs);
+        }
+        return () => {
+            cancelled = true;
+            if (intervalId !== undefined)
+                clearInterval(intervalId);
+        };
+    }, [includeBattery, batteryPollIntervalMs]);
+    return data;
+}
+
+exports.getDeviceData = getDeviceData;
 exports.useClipboard = useClipboard;
+exports.useDeviceData = useDeviceData;
 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;

package/dist/useDeviceData.d.ts

@@ -0,0 +1,82 @@
+/** Parsed Client Hints from `navigator.userAgentData` when available */
+export interface UserAgentDataInfo {
+    mobile: boolean;
+    platform: string;
+    brands: ReadonlyArray<{
+        brand: string;
+        version: string;
+    }>;
+}
+/** Screen and display metrics from `screen` and `window` */
+export interface DeviceScreenInfo {
+    width: number;
+    height: number;
+    availWidth: number;
+    availHeight: number;
+    colorDepth: number;
+    pixelRatio: number;
+}
+/** Viewport size (`window.innerWidth` / `innerHeight`) */
+export interface DeviceViewportInfo {
+    width: number;
+    height: number;
+}
+/** Battery status from the Battery Status API when available */
+export interface DeviceBatteryInfo {
+    charging: boolean;
+    level: number;
+}
+/** Snapshot of device / browser data from native Navigator and related APIs */
+export interface DeviceData {
+    userAgent: string;
+    language: string;
+    languages: readonly string[];
+    platform: string;
+    cookieEnabled: boolean;
+    online: boolean;
+    hardwareConcurrency?: number;
+    /** Approximate device RAM in GB (Chrome / some browsers only) */
+    deviceMemory?: number;
+    maxTouchPoints: number;
+    vendor: string;
+    touch: boolean;
+    screen: DeviceScreenInfo;
+    viewport: DeviceViewportInfo;
+    userAgentData?: UserAgentDataInfo;
+    reducedMotion: boolean;
+    colorScheme: "light" | "dark" | "no-preference";
+    battery?: DeviceBatteryInfo;
+}
+export interface UseDeviceDataOptions {
+    /** Fetch battery info when the Battery Status API exists (default: true) */
+    includeBattery?: boolean;
+    /** Battery refresh interval in ms (default: 60000) */
+    batteryPollIntervalMs?: number;
+}
+/** Reads synchronous device / browser data from Navigator, Screen, and matchMedia. */
+export declare function getDeviceData(): DeviceData;
+/**
+ * Extracts device and browser data from native Navigator, Screen, window, and
+ * matchMedia APIs. Updates on resize, orientation, online/offline, and
+ * prefers-color-scheme / prefers-reduced-motion changes. Optionally polls the
+ * Battery Status API when available.
+ *
+ * @param options - `includeBattery` (default true), `batteryPollIntervalMs` (default 60000)
+ * @returns Current {@link DeviceData} snapshot
+ *
+ * @example
+ * ```tsx
+ * function DevicePanel() {
+ *   const device = useDeviceData();
+ *   return (
+ *     <dl>
+ *       <dt>Language</dt><dd>{device.language}</dd>
+ *       <dt>CPUs</dt><dd>{device.hardwareConcurrency ?? '—'}</dd>
+ *       <dt>Viewport</dt><dd>{device.viewport.width}×{device.viewport.height}</dd>
+ *       <dt>Theme</dt><dd>{device.colorScheme}</dd>
+ *     </dl>
+ *   );
+ * }
+ * ```
+ */
+export declare function useDeviceData(options?: UseDeviceDataOptions): DeviceData;

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/docs/README.md

@@ -41,7 +41,9 @@ 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.                                                                                                                                                                   |
+| **useDeviceData**          | Live device/browser snapshot: language, CPUs, memory, viewport, screen, touch, color scheme, reduced motion, Client Hints.                                                                              |
 | **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.                                                                                                                                                                   |

package/docs/main.js

@@ -22,6 +22,8 @@ const {
   useRefPrint,
   useRBAC,
   usePrefetch,
+  usePoll,
+  useDeviceData,
 } = await import(
   isLocal ? '../dist/index.module.js' : 'https://unpkg.com/preact-missing-hooks/dist/index.module.js'
 );
@@ -85,6 +87,33 @@ function DemoNetworkState() {
   );
 }
 
+function DemoDeviceData() {
+  const device = useDeviceData({ includeBattery: false });
+  const rows = [
+    ['Language', device.language],
+    ['Platform', device.platform || device.userAgentData?.platform || '—'],
+    ['CPUs', device.hardwareConcurrency != null ? String(device.hardwareConcurrency) : '—'],
+    ['Memory (GB)', device.deviceMemory != null ? String(device.deviceMemory) : '—'],
+    ['Viewport', device.viewport.width + '×' + device.viewport.height],
+    ['Screen', device.screen.width + '×' + device.screen.height],
+    ['Touch', device.touch ? 'yes' : 'no'],
+    ['Color scheme', device.colorScheme],
+    ['Reduced motion', device.reducedMotion ? 'yes' : 'no'],
+    ['Online', device.online ? 'yes' : 'no'],
+  ];
+  if (device.userAgentData?.mobile) {
+    rows.push(['Mobile (UA-CH)', 'yes']);
+  }
+  return h('div', { class: 'status', style: { fontSize: '0.85rem' } },
+    rows.map(([label, value]) =>
+      h('div', { key: label, style: { marginBottom: '0.25rem' } },
+        h('strong', {}, label + ': '),
+        value
+      )
+    )
+  );
+}
+
 function DemoPrefetch() {
   const { prefetch, isPrefetched } = usePrefetch();
   const [lastUrl, setLastUrl] = useState('');
@@ -111,6 +140,29 @@ function DemoPrefetch() {
   );
 }
 
+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('');
@@ -538,6 +590,13 @@ const HOOKS = [
     code: `const state = useNetworkState();\n// state.online, state.effectiveType, ...`,
     Live: DemoNetworkState,
   },
+  {
+    name: 'useDeviceData',
+    flow: 'Component → useDeviceData() → Navigator + Screen + matchMedia (+ optional Battery API)',
+    summary: 'Extracts device/browser data: language, platform, CPUs, memory, screen, viewport, touch, color scheme, reduced motion, Client Hints, and optional battery.',
+    code: `const device = useDeviceData();\n// device.language, device.hardwareConcurrency, device.viewport, device.colorScheme`,
+    Live: DemoDeviceData,
+  },
   {
     name: 'usePrefetch',
     flow: 'Component → usePrefetch() → prefetch(url, options?) → link rel=prefetch or fetch()',
@@ -545,6 +604,13 @@ const HOOKS = [
     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',