@dloizides/rn-web-hooks 1.0.1

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 1.0.0
+
+Initial release. Extracted verbatim from the byte-identical `hooks/useOnlineStatus`,
+`hooks/useEscapeKey`, `hooks/useHighContrast`, and `utils/debounce` modules in
+`katalogos-web` and `erevna-web` (extract-on-second-use). The only change is
+`debounce` now imports `isValueDefined` directly from `@dloizides/utils` instead of
+a local re-export shim.
+
+- `useOnlineStatus`, `useEscapeKey`, `useHighContrast`
+- `debounce`, `throttle`, `useDebouncedCallback`

package/README.md

@@ -0,0 +1,31 @@
+# @dloizides/rn-web-hooks
+
+Cross-platform (React Native + `react-native-web`) React hooks and rate-limiting
+helpers, extracted from the byte-identical copies in `katalogos-web` and `erevna-web`.
+
+| Export | What |
+|---|---|
+| `useOnlineStatus()` | `{ isOnline, isOffline }` via `navigator.onLine` + online/offline events (web); always online on native |
+| `useEscapeKey(handler, enabled?)` | fires `handler` on Escape keydown (web only, no-op native) |
+| `useHighContrast()` | tracks `prefers-contrast: more` (web only, `false` native) |
+| `debounce(fn, wait?)` | plain debounced function |
+| `throttle(fn, wait?)` | plain throttled function |
+| `useDebouncedCallback(cb, wait)` | stable debounced callback with `.flush()` / `.cancel()`, flushes on unmount |
+
+## Install
+
+```sh
+npm install @dloizides/rn-web-hooks
+```
+
+Peers: `react` (>=18), `react-native` (>=0.79). Runtime dep: `@dloizides/utils`.
+
+## Usage
+
+```ts
+import { useOnlineStatus, useEscapeKey, useDebouncedCallback } from '@dloizides/rn-web-hooks';
+
+const { isOffline } = useOnlineStatus();
+useEscapeKey(() => setOpen(false), open);
+const debouncedSave = useDebouncedCallback((v: string) => save(v), 300);
+```

package/dist/index.d.mts

@@ -0,0 +1,46 @@
+interface OnlineStatus {
+    /** Whether the browser currently has network connectivity. */
+    isOnline: boolean;
+    /** Whether the browser is currently offline. */
+    isOffline: boolean;
+}
+/**
+ * Tracks browser online/offline status via `navigator.onLine`
+ * and the `online`/`offline` window events.
+ *
+ * On native platforms, always reports as online (native apps
+ * handle connectivity differently via React Query).
+ */
+declare function useOnlineStatus(): OnlineStatus;
+
+declare function useEscapeKey(handler: () => void, enabled?: boolean): void;
+
+declare function useHighContrast(): boolean;
+
+/**
+ * Debounce and throttle utilities for rate limiting function calls.
+ */
+declare function debounce<T extends (...args: readonly unknown[]) => unknown>(fn: T, wait?: number): (...args: Parameters<T>) => void;
+/**
+ * Creates a throttled version of a function that only invokes at most once
+ * per every `wait` milliseconds.
+ *
+ * @param fn - The function to throttle
+ * @param wait - The number of milliseconds to wait between invocations (default: 300)
+ * @returns A throttled version of the function
+ *
+ * @example
+ * const throttledUpdate = throttle(updatePosition, 100);
+ * // Rapid calls will only trigger updatePosition every 100ms
+ */
+declare function throttle<T extends (...args: readonly unknown[]) => unknown>(fn: T, wait?: number): (...args: Parameters<T>) => void;
+interface DebouncedCallback<T extends (...args: readonly unknown[]) => unknown> {
+    (...args: Parameters<T>): void;
+    /** Fire the pending call now (if any) and clear it. No-op if nothing pending. */
+    flush: () => void;
+    /** Drop the pending call (if any) without firing it. No-op if nothing pending. */
+    cancel: () => void;
+}
+declare function useDebouncedCallback<T extends (...args: readonly unknown[]) => unknown>(callback: T, wait: number): DebouncedCallback<T>;
+
+export { debounce, throttle, useDebouncedCallback, useEscapeKey, useHighContrast, useOnlineStatus };

package/dist/index.d.ts

@@ -0,0 +1,46 @@
+interface OnlineStatus {
+    /** Whether the browser currently has network connectivity. */
+    isOnline: boolean;
+    /** Whether the browser is currently offline. */
+    isOffline: boolean;
+}
+/**
+ * Tracks browser online/offline status via `navigator.onLine`
+ * and the `online`/`offline` window events.
+ *
+ * On native platforms, always reports as online (native apps
+ * handle connectivity differently via React Query).
+ */
+declare function useOnlineStatus(): OnlineStatus;
+
+declare function useEscapeKey(handler: () => void, enabled?: boolean): void;
+
+declare function useHighContrast(): boolean;
+
+/**
+ * Debounce and throttle utilities for rate limiting function calls.
+ */
+declare function debounce<T extends (...args: readonly unknown[]) => unknown>(fn: T, wait?: number): (...args: Parameters<T>) => void;
+/**
+ * Creates a throttled version of a function that only invokes at most once
+ * per every `wait` milliseconds.
+ *
+ * @param fn - The function to throttle
+ * @param wait - The number of milliseconds to wait between invocations (default: 300)
+ * @returns A throttled version of the function
+ *
+ * @example
+ * const throttledUpdate = throttle(updatePosition, 100);
+ * // Rapid calls will only trigger updatePosition every 100ms
+ */
+declare function throttle<T extends (...args: readonly unknown[]) => unknown>(fn: T, wait?: number): (...args: Parameters<T>) => void;
+interface DebouncedCallback<T extends (...args: readonly unknown[]) => unknown> {
+    (...args: Parameters<T>): void;
+    /** Fire the pending call now (if any) and clear it. No-op if nothing pending. */
+    flush: () => void;
+    /** Drop the pending call (if any) without firing it. No-op if nothing pending. */
+    cancel: () => void;
+}
+declare function useDebouncedCallback<T extends (...args: readonly unknown[]) => unknown>(callback: T, wait: number): DebouncedCallback<T>;
+
+export { debounce, throttle, useDebouncedCallback, useEscapeKey, useHighContrast, useOnlineStatus };

package/dist/index.js

@@ -0,0 +1,159 @@
+'use strict';
+
+var react = require('react');
+var reactNative = require('react-native');
+var utils = require('@dloizides/utils');
+
+// src/useOnlineStatus.ts
+function isWebPlatform() {
+  return reactNative.Platform.OS === "web";
+}
+function getBrowserOnlineState() {
+  if (typeof navigator === "undefined") return true;
+  return navigator.onLine;
+}
+function useOnlineStatus() {
+  const [isOnline, setIsOnline] = react.useState(() => {
+    if (!isWebPlatform()) return true;
+    return getBrowserOnlineState();
+  });
+  const handleOnline = react.useCallback(() => {
+    setIsOnline(true);
+  }, []);
+  const handleOffline = react.useCallback(() => {
+    setIsOnline(false);
+  }, []);
+  react.useEffect(() => {
+    if (!isWebPlatform()) return;
+    if (typeof window === "undefined") return;
+    window.addEventListener("online", handleOnline);
+    window.addEventListener("offline", handleOffline);
+    return () => {
+      window.removeEventListener("online", handleOnline);
+      window.removeEventListener("offline", handleOffline);
+    };
+  }, [handleOnline, handleOffline]);
+  return { isOnline, isOffline: !isOnline };
+}
+function useEscapeKey(handler, enabled = true) {
+  react.useEffect(() => {
+    if (reactNative.Platform.OS !== "web" || !enabled) return;
+    const listener = (e) => {
+      if (e.key === "Escape") handler();
+    };
+    document.addEventListener("keydown", listener);
+    return () => {
+      document.removeEventListener("keydown", listener);
+    };
+  }, [handler, enabled]);
+}
+var HIGH_CONTRAST_QUERY = "(prefers-contrast: more)";
+function useHighContrast() {
+  const [isHighContrast, setIsHighContrast] = react.useState(() => {
+    if (reactNative.Platform.OS !== "web") return false;
+    return window.matchMedia(HIGH_CONTRAST_QUERY).matches;
+  });
+  react.useEffect(() => {
+    if (reactNative.Platform.OS !== "web") return;
+    const mql = window.matchMedia(HIGH_CONTRAST_QUERY);
+    const handler = (e) => {
+      setIsHighContrast(e.matches);
+    };
+    mql.addEventListener("change", handler);
+    return () => {
+      mql.removeEventListener("change", handler);
+    };
+  }, []);
+  return isHighContrast;
+}
+function debounce(fn, wait = 300) {
+  let timeoutId = null;
+  return function debounced(...args) {
+    if (utils.isValueDefined(timeoutId))
+      clearTimeout(timeoutId);
+    timeoutId = setTimeout(() => {
+      fn(...args);
+      timeoutId = null;
+    }, wait);
+  };
+}
+function throttle(fn, wait = 300) {
+  let lastCallTime = null;
+  let timeoutId = null;
+  return function throttled(...args) {
+    const now = Date.now();
+    if (!utils.isValueDefined(lastCallTime) || now - lastCallTime >= wait) {
+      lastCallTime = now;
+      fn(...args);
+    } else {
+      if (utils.isValueDefined(timeoutId))
+        clearTimeout(timeoutId);
+      const remaining = wait - (now - lastCallTime);
+      timeoutId = setTimeout(() => {
+        lastCallTime = Date.now();
+        fn(...args);
+        timeoutId = null;
+      }, remaining);
+    }
+  };
+}
+function flushPending(stateRef) {
+  const state = stateRef.current;
+  if (!utils.isValueDefined(state.timeoutId) || !utils.isValueDefined(state.pendingArgs)) return;
+  clearTimeout(state.timeoutId);
+  const args = state.pendingArgs;
+  state.timeoutId = null;
+  state.pendingArgs = null;
+  state.callback(...args);
+}
+function cancelPending(stateRef) {
+  const state = stateRef.current;
+  if (utils.isValueDefined(state.timeoutId)) clearTimeout(state.timeoutId);
+  state.timeoutId = null;
+  state.pendingArgs = null;
+}
+function schedulePending(stateRef, args, wait) {
+  const state = stateRef.current;
+  if (utils.isValueDefined(state.timeoutId)) clearTimeout(state.timeoutId);
+  state.pendingArgs = args;
+  state.timeoutId = setTimeout(() => {
+    state.callback(...args);
+    state.timeoutId = null;
+    state.pendingArgs = null;
+  }, wait);
+}
+function useDebouncedCallback(callback, wait) {
+  const stateRef = react.useRef({ timeoutId: null, pendingArgs: null, callback });
+  react.useEffect(() => {
+    stateRef.current.callback = callback;
+  }, [callback]);
+  const result = react.useMemo(
+    () => Object.assign(
+      (...args) => {
+        schedulePending(stateRef, args, wait);
+      },
+      {
+        flush: () => {
+          flushPending(stateRef);
+        },
+        cancel: () => {
+          cancelPending(stateRef);
+        }
+      }
+    ),
+    [wait]
+  );
+  react.useEffect(() => () => {
+    result.flush();
+  }, [result]);
+  return result;
+}
+
+exports.debounce = debounce;
+exports.throttle = throttle;
+exports.useDebouncedCallback = useDebouncedCallback;
+exports.useEscapeKey = useEscapeKey;
+exports.useHighContrast = useHighContrast;
+exports.useOnlineStatus = useOnlineStatus;
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/useOnlineStatus.ts","../src/useEscapeKey.ts","../src/useHighContrast.ts","../src/debounce.ts"],"names":["Platform","useState","useCallback","useEffect","isValueDefined","useRef","useMemo"],"mappings":"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","file":"index.js","sourcesContent":["/**\n * Hook to track the browser's online/offline status.\n * Web-only — native apps use React Query's built-in caching.\n *\n * Uses `navigator.onLine` for initial state and listens to\n * `online`/`offline` window events for real-time updates.\n */\nimport { useCallback, useEffect, useState } from 'react';\n\nimport { Platform } from 'react-native';\n\ninterface OnlineStatus {\n  /** Whether the browser currently has network connectivity. */\n  isOnline: boolean;\n  /** Whether the browser is currently offline. */\n  isOffline: boolean;\n}\n\n/** Returns true when running on the web platform. */\nfunction isWebPlatform(): boolean {\n  return Platform.OS === 'web';\n}\n\n/** Reads the current browser online state safely. */\nfunction getBrowserOnlineState(): boolean {\n  if (typeof navigator === 'undefined') return true;\n  return navigator.onLine;\n}\n\n/**\n * Tracks browser online/offline status via `navigator.onLine`\n * and the `online`/`offline` window events.\n *\n * On native platforms, always reports as online (native apps\n * handle connectivity differently via React Query).\n */\nexport function useOnlineStatus(): OnlineStatus {\n  const [isOnline, setIsOnline] = useState<boolean>(() => {\n    if (!isWebPlatform()) return true;\n    return getBrowserOnlineState();\n  });\n\n  const handleOnline = useCallback((): void => {\n    setIsOnline(true);\n  }, []);\n\n  const handleOffline = useCallback((): void => {\n    setIsOnline(false);\n  }, []);\n\n  useEffect(() => {\n    if (!isWebPlatform()) return;\n    if (typeof window === 'undefined') return;\n\n    window.addEventListener('online', handleOnline);\n    window.addEventListener('offline', handleOffline);\n\n    return () => {\n      window.removeEventListener('online', handleOnline);\n      window.removeEventListener('offline', handleOffline);\n    };\n  }, [handleOnline, handleOffline]);\n\n  return { isOnline, isOffline: !isOnline };\n}\n","/**\n * Calls the provided handler when the Escape key is pressed.\n * Web only -- no-op on native platforms.\n */\nimport { useEffect } from 'react';\n\nimport { Platform } from 'react-native';\n\nexport function useEscapeKey(handler: () => void, enabled = true): void {\n  useEffect(() => {\n    if (Platform.OS !== 'web' || !enabled) return;\n\n    const listener = (e: KeyboardEvent): void => {\n      if (e.key === 'Escape') handler();\n    };\n\n    document.addEventListener('keydown', listener);\n    return () => {\n      document.removeEventListener('keydown', listener);\n    };\n  }, [handler, enabled]);\n}\n","/**\n * Detects whether the user has enabled a high contrast preference\n * via the `prefers-contrast: more` media query.\n *\n * Web only -- returns `false` on native platforms where the media\n * query is not available.\n */\nimport { useEffect, useState } from 'react';\n\nimport { Platform } from 'react-native';\n\nconst HIGH_CONTRAST_QUERY = '(prefers-contrast: more)';\n\nexport function useHighContrast(): boolean {\n  const [isHighContrast, setIsHighContrast] = useState(() => {\n    if (Platform.OS !== 'web') return false;\n    return window.matchMedia(HIGH_CONTRAST_QUERY).matches;\n  });\n\n  useEffect(() => {\n    if (Platform.OS !== 'web') return;\n\n    const mql = window.matchMedia(HIGH_CONTRAST_QUERY);\n    const handler = (e: MediaQueryListEvent): void => {\n      setIsHighContrast(e.matches);\n    };\n\n    mql.addEventListener('change', handler);\n    return () => {\n      mql.removeEventListener('change', handler);\n    };\n  }, []);\n\n  return isHighContrast;\n}\n","/**\n * Debounce and throttle utilities for rate limiting function calls.\n */\n\n/**\n * Creates a debounced version of a function that delays invoking until after\n * `wait` milliseconds have elapsed since the last time it was invoked.\n *\n * @param fn - The function to debounce\n * @param wait - The number of milliseconds to delay (default: 300)\n * @returns A debounced version of the function\n *\n * @example\n * const debouncedSave = debounce(saveData, 500);\n * // Rapid calls will only trigger saveData after 500ms of inactivity\n */\n/**\n * React hook for creating a debounced callback.\n * The callback reference is stable and won't cause re-renders.\n *\n * @param callback - The callback function to debounce\n * @param wait - The debounce delay in milliseconds\n * @param deps - Dependencies array (similar to useCallback)\n * @returns A stable debounced callback\n *\n * @example\n * const debouncedSearch = useDebouncedCallback(\n *   (query: string) => searchAPI(query),\n *   300,\n *   []\n * );\n */\nimport { useMemo, useRef, useEffect } from 'react';\n\nimport { isValueDefined } from '@dloizides/utils';\n\nexport function debounce<T extends (...args: readonly unknown[]) => unknown>(\n  fn: T,\n  wait: number = 300\n): (...args: Parameters<T>) => void {\n  let timeoutId: ReturnType<typeof setTimeout> | null = null;\n\n  return function debounced(...args: Parameters<T>) {\n    if (isValueDefined(timeoutId)) \n      clearTimeout(timeoutId);\n    \n    timeoutId = setTimeout(() => {\n      fn(...args);\n      timeoutId = null;\n    }, wait);\n  };\n}\n\n/**\n * Creates a throttled version of a function that only invokes at most once\n * per every `wait` milliseconds.\n *\n * @param fn - The function to throttle\n * @param wait - The number of milliseconds to wait between invocations (default: 300)\n * @returns A throttled version of the function\n *\n * @example\n * const throttledUpdate = throttle(updatePosition, 100);\n * // Rapid calls will only trigger updatePosition every 100ms\n */\nexport function throttle<T extends (...args: readonly unknown[]) => unknown>(\n  fn: T,\n  wait: number = 300\n): (...args: Parameters<T>) => void {\n  let lastCallTime: number | null = null;\n  let timeoutId: ReturnType<typeof setTimeout> | null = null;\n\n  return function throttled(...args: Parameters<T>) {\n    const now = Date.now();\n\n    if (!isValueDefined(lastCallTime) || now - lastCallTime >= wait) {\n      // Enough time has passed, call immediately\n      lastCallTime = now;\n      fn(...args);\n    } else {\n      // Schedule a call for the end of the wait period\n      if (isValueDefined(timeoutId)) \n        clearTimeout(timeoutId);\n      \n      const remaining = wait - (now - lastCallTime);\n      timeoutId = setTimeout(() => {\n        lastCallTime = Date.now();\n        fn(...args);\n        timeoutId = null;\n      }, remaining);\n    }\n  };\n}\n\ninterface DebouncedCallback<T extends (...args: readonly unknown[]) => unknown> {\n  (...args: Parameters<T>): void;\n  /** Fire the pending call now (if any) and clear it. No-op if nothing pending. */\n  flush: () => void;\n  /** Drop the pending call (if any) without firing it. No-op if nothing pending. */\n  cancel: () => void;\n}\n\n/**\n * Mutable bookkeeping shared by the scheduled call, `flush` and `cancel`. Held\n * in a single ref so the helpers below can be plain module functions (keeps\n * `useDebouncedCallback` itself small and avoids reading refs during render).\n */\ninterface DebounceState<T extends (...args: readonly unknown[]) => unknown> {\n  timeoutId: ReturnType<typeof setTimeout> | null;\n  pendingArgs: Parameters<T> | null;\n  callback: T;\n}\n\ninterface DebounceStateRef<T extends (...args: readonly unknown[]) => unknown> {\n  current: DebounceState<T>;\n}\n\n/** Fire the pending call now (if any) and clear it. */\nfunction flushPending<T extends (...args: readonly unknown[]) => unknown>(\n  stateRef: DebounceStateRef<T>\n): void {\n  const state = stateRef.current;\n  if (!isValueDefined(state.timeoutId) || !isValueDefined(state.pendingArgs)) return;\n  clearTimeout(state.timeoutId);\n  const args = state.pendingArgs;\n  state.timeoutId = null;\n  state.pendingArgs = null;\n  state.callback(...args);\n}\n\n/** Drop the pending call (if any) without firing it. */\nfunction cancelPending<T extends (...args: readonly unknown[]) => unknown>(\n  stateRef: DebounceStateRef<T>\n): void {\n  const state = stateRef.current;\n  if (isValueDefined(state.timeoutId)) clearTimeout(state.timeoutId);\n  state.timeoutId = null;\n  state.pendingArgs = null;\n}\n\n/** (Re)schedule the trailing-edge call for `wait` ms from now. */\nfunction schedulePending<T extends (...args: readonly unknown[]) => unknown>(\n  stateRef: DebounceStateRef<T>,\n  args: Parameters<T>,\n  wait: number\n): void {\n  const state = stateRef.current;\n  if (isValueDefined(state.timeoutId)) clearTimeout(state.timeoutId);\n  state.pendingArgs = args;\n  state.timeoutId = setTimeout(() => {\n    state.callback(...args);\n    state.timeoutId = null;\n    state.pendingArgs = null;\n  }, wait);\n}\n\nexport function useDebouncedCallback<T extends (...args: readonly unknown[]) => unknown>(\n  callback: T,\n  wait: number\n): DebouncedCallback<T> {\n  const stateRef = useRef<DebounceState<T>>({ timeoutId: null, pendingArgs: null, callback });\n\n  // Update callback ref when callback changes\n  useEffect(() => {\n    stateRef.current.callback = callback;\n  }, [callback]);\n\n  // The callable + flush/cancel are built in one expression so no value React\n  // has already memoised gets mutated afterwards (react-compiler safe), and no\n  // type assertion is needed — Object.assign yields the intersection type.\n  const result = useMemo<DebouncedCallback<T>>(\n    () =>\n      Object.assign(\n        (...args: Parameters<T>): void => { schedulePending(stateRef, args, wait); },\n        {\n          flush: (): void => { flushPending(stateRef); },\n          cancel: (): void => { cancelPending(stateRef); },\n        }\n      ),\n    [wait]\n  );\n\n  // On unmount, fire any pending save synchronously so navigation away\n  // doesn't drop in-flight changes (e.g., an uploaded image whose autoSave\n  // debounce hadn't fired yet).\n  useEffect(() => () => { result.flush(); }, [result]);\n\n  return result;\n}\n"]}

package/dist/index.mjs

@@ -0,0 +1,152 @@
+import { useState, useCallback, useEffect, useRef, useMemo } from 'react';
+import { Platform } from 'react-native';
+import { isValueDefined } from '@dloizides/utils';
+
+// src/useOnlineStatus.ts
+function isWebPlatform() {
+  return Platform.OS === "web";
+}
+function getBrowserOnlineState() {
+  if (typeof navigator === "undefined") return true;
+  return navigator.onLine;
+}
+function useOnlineStatus() {
+  const [isOnline, setIsOnline] = useState(() => {
+    if (!isWebPlatform()) return true;
+    return getBrowserOnlineState();
+  });
+  const handleOnline = useCallback(() => {
+    setIsOnline(true);
+  }, []);
+  const handleOffline = useCallback(() => {
+    setIsOnline(false);
+  }, []);
+  useEffect(() => {
+    if (!isWebPlatform()) return;
+    if (typeof window === "undefined") return;
+    window.addEventListener("online", handleOnline);
+    window.addEventListener("offline", handleOffline);
+    return () => {
+      window.removeEventListener("online", handleOnline);
+      window.removeEventListener("offline", handleOffline);
+    };
+  }, [handleOnline, handleOffline]);
+  return { isOnline, isOffline: !isOnline };
+}
+function useEscapeKey(handler, enabled = true) {
+  useEffect(() => {
+    if (Platform.OS !== "web" || !enabled) return;
+    const listener = (e) => {
+      if (e.key === "Escape") handler();
+    };
+    document.addEventListener("keydown", listener);
+    return () => {
+      document.removeEventListener("keydown", listener);
+    };
+  }, [handler, enabled]);
+}
+var HIGH_CONTRAST_QUERY = "(prefers-contrast: more)";
+function useHighContrast() {
+  const [isHighContrast, setIsHighContrast] = useState(() => {
+    if (Platform.OS !== "web") return false;
+    return window.matchMedia(HIGH_CONTRAST_QUERY).matches;
+  });
+  useEffect(() => {
+    if (Platform.OS !== "web") return;
+    const mql = window.matchMedia(HIGH_CONTRAST_QUERY);
+    const handler = (e) => {
+      setIsHighContrast(e.matches);
+    };
+    mql.addEventListener("change", handler);
+    return () => {
+      mql.removeEventListener("change", handler);
+    };
+  }, []);
+  return isHighContrast;
+}
+function debounce(fn, wait = 300) {
+  let timeoutId = null;
+  return function debounced(...args) {
+    if (isValueDefined(timeoutId))
+      clearTimeout(timeoutId);
+    timeoutId = setTimeout(() => {
+      fn(...args);
+      timeoutId = null;
+    }, wait);
+  };
+}
+function throttle(fn, wait = 300) {
+  let lastCallTime = null;
+  let timeoutId = null;
+  return function throttled(...args) {
+    const now = Date.now();
+    if (!isValueDefined(lastCallTime) || now - lastCallTime >= wait) {
+      lastCallTime = now;
+      fn(...args);
+    } else {
+      if (isValueDefined(timeoutId))
+        clearTimeout(timeoutId);
+      const remaining = wait - (now - lastCallTime);
+      timeoutId = setTimeout(() => {
+        lastCallTime = Date.now();
+        fn(...args);
+        timeoutId = null;
+      }, remaining);
+    }
+  };
+}
+function flushPending(stateRef) {
+  const state = stateRef.current;
+  if (!isValueDefined(state.timeoutId) || !isValueDefined(state.pendingArgs)) return;
+  clearTimeout(state.timeoutId);
+  const args = state.pendingArgs;
+  state.timeoutId = null;
+  state.pendingArgs = null;
+  state.callback(...args);
+}
+function cancelPending(stateRef) {
+  const state = stateRef.current;
+  if (isValueDefined(state.timeoutId)) clearTimeout(state.timeoutId);
+  state.timeoutId = null;
+  state.pendingArgs = null;
+}
+function schedulePending(stateRef, args, wait) {
+  const state = stateRef.current;
+  if (isValueDefined(state.timeoutId)) clearTimeout(state.timeoutId);
+  state.pendingArgs = args;
+  state.timeoutId = setTimeout(() => {
+    state.callback(...args);
+    state.timeoutId = null;
+    state.pendingArgs = null;
+  }, wait);
+}
+function useDebouncedCallback(callback, wait) {
+  const stateRef = useRef({ timeoutId: null, pendingArgs: null, callback });
+  useEffect(() => {
+    stateRef.current.callback = callback;
+  }, [callback]);
+  const result = useMemo(
+    () => Object.assign(
+      (...args) => {
+        schedulePending(stateRef, args, wait);
+      },
+      {
+        flush: () => {
+          flushPending(stateRef);
+        },
+        cancel: () => {
+          cancelPending(stateRef);
+        }
+      }
+    ),
+    [wait]
+  );
+  useEffect(() => () => {
+    result.flush();
+  }, [result]);
+  return result;
+}
+
+export { debounce, throttle, useDebouncedCallback, useEscapeKey, useHighContrast, useOnlineStatus };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/useOnlineStatus.ts","../src/useEscapeKey.ts","../src/useHighContrast.ts","../src/debounce.ts"],"names":["useEffect","Platform","useState"],"mappings":"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","file":"index.mjs","sourcesContent":["/**\n * Hook to track the browser's online/offline status.\n * Web-only — native apps use React Query's built-in caching.\n *\n * Uses `navigator.onLine` for initial state and listens to\n * `online`/`offline` window events for real-time updates.\n */\nimport { useCallback, useEffect, useState } from 'react';\n\nimport { Platform } from 'react-native';\n\ninterface OnlineStatus {\n  /** Whether the browser currently has network connectivity. */\n  isOnline: boolean;\n  /** Whether the browser is currently offline. */\n  isOffline: boolean;\n}\n\n/** Returns true when running on the web platform. */\nfunction isWebPlatform(): boolean {\n  return Platform.OS === 'web';\n}\n\n/** Reads the current browser online state safely. */\nfunction getBrowserOnlineState(): boolean {\n  if (typeof navigator === 'undefined') return true;\n  return navigator.onLine;\n}\n\n/**\n * Tracks browser online/offline status via `navigator.onLine`\n * and the `online`/`offline` window events.\n *\n * On native platforms, always reports as online (native apps\n * handle connectivity differently via React Query).\n */\nexport function useOnlineStatus(): OnlineStatus {\n  const [isOnline, setIsOnline] = useState<boolean>(() => {\n    if (!isWebPlatform()) return true;\n    return getBrowserOnlineState();\n  });\n\n  const handleOnline = useCallback((): void => {\n    setIsOnline(true);\n  }, []);\n\n  const handleOffline = useCallback((): void => {\n    setIsOnline(false);\n  }, []);\n\n  useEffect(() => {\n    if (!isWebPlatform()) return;\n    if (typeof window === 'undefined') return;\n\n    window.addEventListener('online', handleOnline);\n    window.addEventListener('offline', handleOffline);\n\n    return () => {\n      window.removeEventListener('online', handleOnline);\n      window.removeEventListener('offline', handleOffline);\n    };\n  }, [handleOnline, handleOffline]);\n\n  return { isOnline, isOffline: !isOnline };\n}\n","/**\n * Calls the provided handler when the Escape key is pressed.\n * Web only -- no-op on native platforms.\n */\nimport { useEffect } from 'react';\n\nimport { Platform } from 'react-native';\n\nexport function useEscapeKey(handler: () => void, enabled = true): void {\n  useEffect(() => {\n    if (Platform.OS !== 'web' || !enabled) return;\n\n    const listener = (e: KeyboardEvent): void => {\n      if (e.key === 'Escape') handler();\n    };\n\n    document.addEventListener('keydown', listener);\n    return () => {\n      document.removeEventListener('keydown', listener);\n    };\n  }, [handler, enabled]);\n}\n","/**\n * Detects whether the user has enabled a high contrast preference\n * via the `prefers-contrast: more` media query.\n *\n * Web only -- returns `false` on native platforms where the media\n * query is not available.\n */\nimport { useEffect, useState } from 'react';\n\nimport { Platform } from 'react-native';\n\nconst HIGH_CONTRAST_QUERY = '(prefers-contrast: more)';\n\nexport function useHighContrast(): boolean {\n  const [isHighContrast, setIsHighContrast] = useState(() => {\n    if (Platform.OS !== 'web') return false;\n    return window.matchMedia(HIGH_CONTRAST_QUERY).matches;\n  });\n\n  useEffect(() => {\n    if (Platform.OS !== 'web') return;\n\n    const mql = window.matchMedia(HIGH_CONTRAST_QUERY);\n    const handler = (e: MediaQueryListEvent): void => {\n      setIsHighContrast(e.matches);\n    };\n\n    mql.addEventListener('change', handler);\n    return () => {\n      mql.removeEventListener('change', handler);\n    };\n  }, []);\n\n  return isHighContrast;\n}\n","/**\n * Debounce and throttle utilities for rate limiting function calls.\n */\n\n/**\n * Creates a debounced version of a function that delays invoking until after\n * `wait` milliseconds have elapsed since the last time it was invoked.\n *\n * @param fn - The function to debounce\n * @param wait - The number of milliseconds to delay (default: 300)\n * @returns A debounced version of the function\n *\n * @example\n * const debouncedSave = debounce(saveData, 500);\n * // Rapid calls will only trigger saveData after 500ms of inactivity\n */\n/**\n * React hook for creating a debounced callback.\n * The callback reference is stable and won't cause re-renders.\n *\n * @param callback - The callback function to debounce\n * @param wait - The debounce delay in milliseconds\n * @param deps - Dependencies array (similar to useCallback)\n * @returns A stable debounced callback\n *\n * @example\n * const debouncedSearch = useDebouncedCallback(\n *   (query: string) => searchAPI(query),\n *   300,\n *   []\n * );\n */\nimport { useMemo, useRef, useEffect } from 'react';\n\nimport { isValueDefined } from '@dloizides/utils';\n\nexport function debounce<T extends (...args: readonly unknown[]) => unknown>(\n  fn: T,\n  wait: number = 300\n): (...args: Parameters<T>) => void {\n  let timeoutId: ReturnType<typeof setTimeout> | null = null;\n\n  return function debounced(...args: Parameters<T>) {\n    if (isValueDefined(timeoutId)) \n      clearTimeout(timeoutId);\n    \n    timeoutId = setTimeout(() => {\n      fn(...args);\n      timeoutId = null;\n    }, wait);\n  };\n}\n\n/**\n * Creates a throttled version of a function that only invokes at most once\n * per every `wait` milliseconds.\n *\n * @param fn - The function to throttle\n * @param wait - The number of milliseconds to wait between invocations (default: 300)\n * @returns A throttled version of the function\n *\n * @example\n * const throttledUpdate = throttle(updatePosition, 100);\n * // Rapid calls will only trigger updatePosition every 100ms\n */\nexport function throttle<T extends (...args: readonly unknown[]) => unknown>(\n  fn: T,\n  wait: number = 300\n): (...args: Parameters<T>) => void {\n  let lastCallTime: number | null = null;\n  let timeoutId: ReturnType<typeof setTimeout> | null = null;\n\n  return function throttled(...args: Parameters<T>) {\n    const now = Date.now();\n\n    if (!isValueDefined(lastCallTime) || now - lastCallTime >= wait) {\n      // Enough time has passed, call immediately\n      lastCallTime = now;\n      fn(...args);\n    } else {\n      // Schedule a call for the end of the wait period\n      if (isValueDefined(timeoutId)) \n        clearTimeout(timeoutId);\n      \n      const remaining = wait - (now - lastCallTime);\n      timeoutId = setTimeout(() => {\n        lastCallTime = Date.now();\n        fn(...args);\n        timeoutId = null;\n      }, remaining);\n    }\n  };\n}\n\ninterface DebouncedCallback<T extends (...args: readonly unknown[]) => unknown> {\n  (...args: Parameters<T>): void;\n  /** Fire the pending call now (if any) and clear it. No-op if nothing pending. */\n  flush: () => void;\n  /** Drop the pending call (if any) without firing it. No-op if nothing pending. */\n  cancel: () => void;\n}\n\n/**\n * Mutable bookkeeping shared by the scheduled call, `flush` and `cancel`. Held\n * in a single ref so the helpers below can be plain module functions (keeps\n * `useDebouncedCallback` itself small and avoids reading refs during render).\n */\ninterface DebounceState<T extends (...args: readonly unknown[]) => unknown> {\n  timeoutId: ReturnType<typeof setTimeout> | null;\n  pendingArgs: Parameters<T> | null;\n  callback: T;\n}\n\ninterface DebounceStateRef<T extends (...args: readonly unknown[]) => unknown> {\n  current: DebounceState<T>;\n}\n\n/** Fire the pending call now (if any) and clear it. */\nfunction flushPending<T extends (...args: readonly unknown[]) => unknown>(\n  stateRef: DebounceStateRef<T>\n): void {\n  const state = stateRef.current;\n  if (!isValueDefined(state.timeoutId) || !isValueDefined(state.pendingArgs)) return;\n  clearTimeout(state.timeoutId);\n  const args = state.pendingArgs;\n  state.timeoutId = null;\n  state.pendingArgs = null;\n  state.callback(...args);\n}\n\n/** Drop the pending call (if any) without firing it. */\nfunction cancelPending<T extends (...args: readonly unknown[]) => unknown>(\n  stateRef: DebounceStateRef<T>\n): void {\n  const state = stateRef.current;\n  if (isValueDefined(state.timeoutId)) clearTimeout(state.timeoutId);\n  state.timeoutId = null;\n  state.pendingArgs = null;\n}\n\n/** (Re)schedule the trailing-edge call for `wait` ms from now. */\nfunction schedulePending<T extends (...args: readonly unknown[]) => unknown>(\n  stateRef: DebounceStateRef<T>,\n  args: Parameters<T>,\n  wait: number\n): void {\n  const state = stateRef.current;\n  if (isValueDefined(state.timeoutId)) clearTimeout(state.timeoutId);\n  state.pendingArgs = args;\n  state.timeoutId = setTimeout(() => {\n    state.callback(...args);\n    state.timeoutId = null;\n    state.pendingArgs = null;\n  }, wait);\n}\n\nexport function useDebouncedCallback<T extends (...args: readonly unknown[]) => unknown>(\n  callback: T,\n  wait: number\n): DebouncedCallback<T> {\n  const stateRef = useRef<DebounceState<T>>({ timeoutId: null, pendingArgs: null, callback });\n\n  // Update callback ref when callback changes\n  useEffect(() => {\n    stateRef.current.callback = callback;\n  }, [callback]);\n\n  // The callable + flush/cancel are built in one expression so no value React\n  // has already memoised gets mutated afterwards (react-compiler safe), and no\n  // type assertion is needed — Object.assign yields the intersection type.\n  const result = useMemo<DebouncedCallback<T>>(\n    () =>\n      Object.assign(\n        (...args: Parameters<T>): void => { schedulePending(stateRef, args, wait); },\n        {\n          flush: (): void => { flushPending(stateRef); },\n          cancel: (): void => { cancelPending(stateRef); },\n        }\n      ),\n    [wait]\n  );\n\n  // On unmount, fire any pending save synchronously so navigation away\n  // doesn't drop in-flight changes (e.g., an uploaded image whose autoSave\n  // debounce hadn't fired yet).\n  useEffect(() => () => { result.flush(); }, [result]);\n\n  return result;\n}\n"]}

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@dloizides/rn-web-hooks",
+  "version": "1.0.1",
+  "description": "Cross-platform (React Native + web) React hooks and rate-limiting helpers: useOnlineStatus, useEscapeKey, useHighContrast, debounce/throttle/useDebouncedCallback.",
+  "keywords": [
+    "react-hooks",
+    "react-native",
+    "react-native-web",
+    "debounce",
+    "throttle",
+    "online-status"
+  ],
+  "author": "dloizides",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/openmindednewby/rn-web-hooks.git"
+  },
+  "homepage": "https://github.com/openmindednewby/rn-web-hooks#readme",
+  "bugs": {
+    "url": "https://github.com/openmindednewby/rn-web-hooks/issues"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "rimraf dist && tsup",
+    "build:watch": "tsup --watch",
+    "lint": "eslint src --ext .ts",
+    "typecheck": "tsc --noEmit",
+    "clean": "rimraf dist",
+    "security:audit": "npm audit --audit-level=high",
+    "prepublishOnly": "npm run clean && npm run build"
+  },
+  "dependencies": {
+    "@dloizides/utils": "^1.1.0"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-native": ">=0.79.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.32",
+    "@types/react": "^18.2.0",
+    "react": "^18.2.0",
+    "react-native": "0.81.5",
+    "rimraf": "^5.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0"
+  }
+}