preact-missing-hooks 1.0.1 → 1.1.0

package/dist/useClipboard.d.ts

@@ -0,0 +1,36 @@
+export interface UseClipboardOptions {
+    /** Duration in ms to keep `copied` true before resetting. Default: 2000 */
+    resetDelay?: number;
+}
+export interface UseClipboardReturn {
+    /** Copy text to the clipboard. Returns true on success. */
+    copy: (text: string) => Promise<boolean>;
+    /** Read text from the clipboard. Returns empty string if denied or unavailable. */
+    paste: () => Promise<string>;
+    /** Whether the last copy operation succeeded (resets after resetDelay) */
+    copied: boolean;
+    /** Error from the last failed operation, or null */
+    error: Error | null;
+    /** Manually reset copied and error state */
+    reset: () => void;
+}
+/**
+ * A Preact hook for reading and writing the clipboard. Uses the async
+ * Clipboard API when available (requires secure context and user gesture).
+ *
+ * @param options - Optional configuration (e.g., resetDelay for copied state)
+ * @returns Object with copy, paste, copied, error, and reset
+ *
+ * @example
+ * ```tsx
+ * function CopyButton() {
+ *   const { copy, copied, error } = useClipboard();
+ *   return (
+ *     <button onClick={() => copy('Hello!')}>
+ *       {copied ? 'Copied!' : 'Copy'}
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+export declare function useClipboard(options?: UseClipboardOptions): UseClipboardReturn;

package/dist/useEventBus.d.ts

@@ -0,0 +1,10 @@
+type EventMap = Record<string, (...args: any[]) => void>;
+/**
+ * A Preact hook to publish and subscribe to custom events across components.
+ * @returns An object with `emit` and `on` methods.
+ */
+export declare function useEventBus<T extends EventMap>(): {
+    emit: <K extends keyof T>(event: K, ...args: Parameters<T[K]>) => void;
+    on: <K extends keyof T>(event: K, handler: T[K]) => () => void;
+};
+export {};

package/dist/useMutationObserver.d.ts

@@ -0,0 +1,9 @@
+import { RefObject } from 'preact';
+export type UseMutationObserverOptions = MutationObserverInit;
+/**
+ * A Preact hook to observe DOM mutations using MutationObserver.
+ * @param target - The element to observe.
+ * @param callback - Function to call on mutation.
+ * @param options - MutationObserver options.
+ */
+export declare function useMutationObserver(targetRef: RefObject<HTMLElement | null>, callback: MutationCallback, options: MutationObserverInit): void;

package/dist/useNetworkState.d.ts

@@ -0,0 +1,40 @@
+/** Effective connection type from Network Information API */
+export type EffectiveConnectionType = 'slow-2g' | '2g' | '3g' | '4g';
+/** Network connection type (e.g., wifi, cellular) */
+export type ConnectionType = 'bluetooth' | 'cellular' | 'ethernet' | 'mixed' | 'none' | 'other' | 'unknown' | 'wifi';
+export interface NetworkState {
+    /** Whether the browser is online */
+    online: boolean;
+    /** Effective connection type (when supported) */
+    effectiveType?: EffectiveConnectionType;
+    /** Estimated downlink speed in Mbps (when supported) */
+    downlink?: number;
+    /** Estimated round-trip time in ms (when supported) */
+    rtt?: number;
+    /** Whether the user has requested reduced data usage (when supported) */
+    saveData?: boolean;
+    /** Connection type (when supported) */
+    connectionType?: ConnectionType;
+}
+/**
+ * A Preact hook that returns the current network state, including online/offline
+ * status and (when supported) connection type, downlink, RTT, and save-data preference.
+ * Updates reactively when the network state changes.
+ *
+ * @returns The current network state object
+ *
+ * @example
+ * ```tsx
+ * function NetworkStatus() {
+ *   const { online, effectiveType, saveData } = useNetworkState();
+ *   return (
+ *     <div>
+ *       Status: {online ? 'Online' : 'Offline'}
+ *       {effectiveType && ` (${effectiveType})`}
+ *       {saveData && ' - Reduced data mode'}
+ *     </div>
+   * );
+ * }
+ * ```
+ */
+export declare function useNetworkState(): NetworkState;

package/dist/usePreferredTheme.d.ts

@@ -0,0 +1,21 @@
+export type PreferredTheme = 'light' | 'dark' | 'no-preference';
+/**
+ * A Preact hook that returns the user's preferred color scheme based on the
+ * `prefers-color-scheme` media query. Updates reactively when the user changes
+ * their system or browser theme preference.
+ *
+ * @returns The preferred theme: 'light', 'dark', or 'no-preference'
+ *
+ * @example
+ * ```tsx
+ * function ThemeAwareComponent() {
+ *   const theme = usePreferredTheme();
+ *   return (
+ *     <div data-theme={theme}>
+ *       Current preference: {theme}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function usePreferredTheme(): PreferredTheme;

package/dist/useWrappedChildren.d.ts

@@ -0,0 +1,10 @@
+import { ComponentChildren } from 'preact';
+export type InjectableProps = Record<string, any>;
+/**
+ * A Preact hook to wrap children components and inject additional props into them.
+ * @param children - The children to wrap and enhance with props.
+ * @param injectProps - The props to inject into each child component.
+ * @param mergeStrategy - How to handle prop conflicts ('override' | 'preserve'). Defaults to 'preserve'.
+ * @returns Enhanced children with injected props.
+ */
+export declare function useWrappedChildren(children: ComponentChildren, injectProps: InjectableProps, mergeStrategy?: 'override' | 'preserve'): ComponentChildren;

package/package.json

@@ -1,48 +1,64 @@
-{
-  "name": "preact-missing-hooks",
-  "version": "1.0.1",
-  "description": "A lightweight, extendable collection of missing React-like hooks for Preact — plus fresh, powerful new ones designed specifically for modern Preact apps.",
-  "author": "Prakhar Dubey",
-  "license": "ISC",
-  "main": "dist/index.js",
-  "module": "dist/index.module.js",
-  "types": "dist/index.d.ts",
-  "source": "src/index.ts",
-  "exports": {
-    ".": {
-      "import": "./dist/index.module.js",
-      "require": "./dist/index.js",
-      "types": "./dist/index.d.ts"
-    },
-    "./useTransition": {
-      "import": "./dist/useTransition.module.js",
-      "require": "./dist/useTransition.js",
-      "types": "./dist/useTransition.d.ts"
-    }
-  },
-  "scripts": {
-    "build": "microbundle",
-    "dev": "microbundle watch",
-    "prepublishOnly": "npm run build",
-    "test": "echo \"Error: no test specified\" && exit 1"
-  },
-  "keywords": [
-    "preact",
-    "hooks",
-    "usetransition",
-    "react-hooks",
-    "microbundle",
-    "typescript",
-    "preact-hooks"
-  ],
-  "dependencies": {
-    "preact": "^10.26.7"
-  },
-  "devDependencies": {
-    "microbundle": "^0.15.1",
-    "typescript": "^5.8.3"
-  },
-  "peerDependencies": {
-    "preact": ">=10.0.0"
-  }
-}
+{
+  "name": "preact-missing-hooks",
+  "version": "1.1.0",
+  "description": "A lightweight, extendable collection of missing React-like hooks for Preact — plus fresh, powerful new ones designed specifically for modern Preact apps.",
+  "author": "Prakhar Dubey",
+  "license": "MIT",
+  "main": "dist/index.js",
+  "module": "dist/index.module.js",
+  "types": "dist/index.d.ts",
+  "source": "src/index.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.module.js",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./useTransition": {
+      "import": "./dist/useTransition.module.js",
+      "require": "./dist/useTransition.js",
+      "types": "./dist/useTransition.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "microbundle",
+    "dev": "microbundle watch",
+    "prepublishOnly": "npm run build",
+    "test": "vitest run",
+    "type-check": "tsc --noEmit"
+  },
+  "keywords": [
+    "preact",
+    "hooks",
+    "usetransition",
+    "useMutationObserver",
+    "useEventBus",
+    "useWrappedChildren",
+    "usePreferredTheme",
+    "useNetworkState",
+    "useClipboard",
+    "react-hooks",
+    "microbundle",
+    "typescript",
+    "preact-hooks"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/prakhardubey2002/Preact-Missing-Hooks"
+  },
+  "dependencies": {
+    "preact": ">=10.0.0"
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^6.6.3",
+    "@testing-library/preact": "^3.2.4",
+    "@types/jest": "^29.5.14",
+    "jsdom": "^26.1.0",
+    "microbundle": "^0.15.1",
+    "typescript": "^5.8.3",
+    "vitest": "^3.1.4"
+  },
+  "peerDependencies": {
+    "preact": ">=10.0.0"
+  }
+}

package/src/index.ts

@@ -1 +1,7 @@
-export * from './useTransition';
+export * from './useTransition'
+export * from './useMutationObserver'
+export * from './useEventBus'
+export * from './useWrappedChildren'
+export * from './usePreferredTheme'
+export * from './useNetworkState'
+export * from './useClipboard'

package/src/useClipboard.ts

@@ -0,0 +1,97 @@
+import { useCallback, useState } from 'preact/hooks';
+
+export interface UseClipboardOptions {
+  /** Duration in ms to keep `copied` true before resetting. Default: 2000 */
+  resetDelay?: number;
+}
+
+export interface UseClipboardReturn {
+  /** Copy text to the clipboard. Returns true on success. */
+  copy: (text: string) => Promise<boolean>;
+  /** Read text from the clipboard. Returns empty string if denied or unavailable. */
+  paste: () => Promise<string>;
+  /** Whether the last copy operation succeeded (resets after resetDelay) */
+  copied: boolean;
+  /** Error from the last failed operation, or null */
+  error: Error | null;
+  /** Manually reset copied and error state */
+  reset: () => void;
+}
+
+/**
+ * A Preact hook for reading and writing the clipboard. Uses the async
+ * Clipboard API when available (requires secure context and user gesture).
+ *
+ * @param options - Optional configuration (e.g., resetDelay for copied state)
+ * @returns Object with copy, paste, copied, error, and reset
+ *
+ * @example
+ * ```tsx
+ * function CopyButton() {
+ *   const { copy, copied, error } = useClipboard();
+ *   return (
+ *     <button onClick={() => copy('Hello!')}>
+ *       {copied ? 'Copied!' : 'Copy'}
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+export function useClipboard(options: UseClipboardOptions = {}): UseClipboardReturn {
+  const { resetDelay = 2000 } = options;
+
+  const [copied, setCopied] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const reset = useCallback(() => {
+    setCopied(false);
+    setError(null);
+  }, []);
+
+  const copy = useCallback(
+    async (text: string): Promise<boolean> => {
+      setError(null);
+
+      if (typeof navigator === 'undefined' || !navigator.clipboard) {
+        const err = new Error('Clipboard API is not available');
+        setError(err);
+        return false;
+      }
+
+      try {
+        await navigator.clipboard.writeText(text);
+        setCopied(true);
+        if (resetDelay > 0) {
+          setTimeout(() => setCopied(false), resetDelay);
+        }
+        return true;
+      } catch (e) {
+        const err = e instanceof Error ? e : new Error(String(e));
+        setError(err);
+        return false;
+      }
+    },
+    [resetDelay]
+  );
+
+  const paste = useCallback(async (): Promise<string> => {
+    setError(null);
+
+    if (typeof navigator === 'undefined' || !navigator.clipboard) {
+      const err = new Error('Clipboard API is not available');
+      setError(err);
+      return '';
+    }
+
+    try {
+      const text = await navigator.clipboard.readText();
+      return text;
+    } catch (e) {
+      const err = e instanceof Error ? e : new Error(String(e));
+      setError(err);
+      return '';
+    }
+  }, []);
+
+  return { copy, paste, copied, error, reset };
+}

package/src/useEventBus.ts

@@ -0,0 +1,36 @@
+import { useCallback, useEffect } from 'preact/hooks';
+
+type EventMap = Record<string, (...args: any[]) => void>;
+
+const listeners = new Map<string, Set<(...args: any[]) => void>>();
+
+/**
+ * A Preact hook to publish and subscribe to custom events across components.
+ * @returns An object with `emit` and `on` methods.
+ */
+export function useEventBus<T extends EventMap>() {
+  const emit = useCallback(<K extends keyof T>(event: K, ...args: Parameters<T[K]>) => {
+    const handlers = listeners.get(event as string);
+    if (handlers) {
+      handlers.forEach((handler) => handler(...args));
+    }
+  }, []);
+
+  const on = useCallback(<K extends keyof T>(event: K, handler: T[K]) => {
+    let handlers = listeners.get(event as string);
+    if (!handlers) {
+      handlers = new Set();
+      listeners.set(event as string, handlers);
+    }
+    handlers.add(handler);
+
+    return () => {
+      handlers!.delete(handler);
+      if (handlers!.size === 0) {
+        listeners.delete(event as string);
+      }
+    };
+  }, []);
+
+  return { emit, on };
+}

package/src/useMutationObserver.ts

@@ -0,0 +1,26 @@
+import { RefObject } from 'preact'
+import { useEffect } from 'preact/hooks'
+
+export type UseMutationObserverOptions = MutationObserverInit
+
+/**
+ * A Preact hook to observe DOM mutations using MutationObserver.
+ * @param target - The element to observe.
+ * @param callback - Function to call on mutation.
+ * @param options - MutationObserver options.
+ */
+export function useMutationObserver(
+  targetRef: RefObject<HTMLElement | null>,
+  callback: MutationCallback,
+  options: MutationObserverInit
+) {
+  useEffect(() => {
+    const node = targetRef.current
+    if (!node) return
+
+    const observer = new MutationObserver(callback)
+    observer.observe(node, options)
+
+    return () => observer.disconnect()
+  }, [targetRef, callback, options])
+}

package/src/useNetworkState.ts

@@ -0,0 +1,122 @@
+import { useEffect, useState } from 'preact/hooks';
+
+/** Network Information API (not in all browsers) */
+interface NetworkInformation extends EventTarget {
+  effectiveType?: string;
+  downlink?: number;
+  rtt?: number;
+  saveData?: boolean;
+  type?: string;
+}
+
+/** Effective connection type from Network Information API */
+export type EffectiveConnectionType = 'slow-2g' | '2g' | '3g' | '4g';
+
+/** Network connection type (e.g., wifi, cellular) */
+export type ConnectionType =
+  | 'bluetooth'
+  | 'cellular'
+  | 'ethernet'
+  | 'mixed'
+  | 'none'
+  | 'other'
+  | 'unknown'
+  | 'wifi';
+
+export interface NetworkState {
+  /** Whether the browser is online */
+  online: boolean;
+  /** Effective connection type (when supported) */
+  effectiveType?: EffectiveConnectionType;
+  /** Estimated downlink speed in Mbps (when supported) */
+  downlink?: number;
+  /** Estimated round-trip time in ms (when supported) */
+  rtt?: number;
+  /** Whether the user has requested reduced data usage (when supported) */
+  saveData?: boolean;
+  /** Connection type (when supported) */
+  connectionType?: ConnectionType;
+}
+
+function getNetworkState(): NetworkState {
+  if (typeof navigator === 'undefined') {
+    return { online: true };
+  }
+
+  const state: NetworkState = {
+    online: navigator.onLine,
+  };
+
+  const connection =
+    (navigator as Navigator & { connection?: NetworkInformation }).connection;
+
+  if (connection) {
+    if (connection.effectiveType !== undefined) {
+      state.effectiveType = connection.effectiveType as EffectiveConnectionType;
+    }
+    if (connection.downlink !== undefined) {
+      state.downlink = connection.downlink;
+    }
+    if (connection.rtt !== undefined) {
+      state.rtt = connection.rtt;
+    }
+    if (connection.saveData !== undefined) {
+      state.saveData = connection.saveData;
+    }
+    if (connection.type !== undefined) {
+      state.connectionType = connection.type as ConnectionType;
+    }
+  }
+
+  return state;
+}
+
+/**
+ * A Preact hook that returns the current network state, including online/offline
+ * status and (when supported) connection type, downlink, RTT, and save-data preference.
+ * Updates reactively when the network state changes.
+ *
+ * @returns The current network state object
+ *
+ * @example
+ * ```tsx
+ * function NetworkStatus() {
+ *   const { online, effectiveType, saveData } = useNetworkState();
+ *   return (
+ *     <div>
+ *       Status: {online ? 'Online' : 'Offline'}
+ *       {effectiveType && ` (${effectiveType})`}
+ *       {saveData && ' - Reduced data mode'}
+ *     </div>
+   * );
+ * }
+ * ```
+ */
+export function useNetworkState(): NetworkState {
+  const [state, setState] = useState<NetworkState>(getNetworkState);
+
+  useEffect(() => {
+    if (typeof window === 'undefined') return;
+
+    const updateState = () => setState(getNetworkState());
+
+    window.addEventListener('online', updateState);
+    window.addEventListener('offline', updateState);
+
+    const connection = (navigator as Navigator & { connection?: NetworkInformation })
+      .connection;
+    if (connection?.addEventListener) {
+      connection.addEventListener('change', updateState);
+    }
+
+    return () => {
+      window.removeEventListener('online', updateState);
+      window.removeEventListener('offline', updateState);
+      if (connection?.removeEventListener) {
+        connection.removeEventListener('change', updateState);
+      }
+    };
+  }, []);
+
+  return state;
+}

package/src/usePreferredTheme.ts

@@ -0,0 +1,68 @@
+import { useEffect, useState } from 'preact/hooks';
+
+export type PreferredTheme = 'light' | 'dark' | 'no-preference';
+
+/**
+ * A Preact hook that returns the user's preferred color scheme based on the
+ * `prefers-color-scheme` media query. Updates reactively when the user changes
+ * their system or browser theme preference.
+ *
+ * @returns The preferred theme: 'light', 'dark', or 'no-preference'
+ *
+ * @example
+ * ```tsx
+ * function ThemeAwareComponent() {
+ *   const theme = usePreferredTheme();
+ *   return (
+ *     <div data-theme={theme}>
+ *       Current preference: {theme}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function usePreferredTheme(): PreferredTheme {
+  const [theme, setTheme] = useState<PreferredTheme>(() => {
+    if (typeof window === 'undefined') return 'no-preference';
+
+    const darkQuery = window.matchMedia('(prefers-color-scheme: dark)');
+    const lightQuery = window.matchMedia('(prefers-color-scheme: light)');
+
+    if (darkQuery.matches) return 'dark';
+    if (lightQuery.matches) return 'light';
+    return 'no-preference';
+  });
+
+  useEffect(() => {
+    if (typeof window === 'undefined') return;
+
+    const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)');
+
+    const handleChange = (e: MediaQueryListEvent) => {
+      setTheme(e.matches ? 'dark' : 'light');
+    };
+
+    // Re-check in case of no-preference (some browsers don't support light query)
+    const updateTheme = () => {
+      const darkQuery = window.matchMedia('(prefers-color-scheme: dark)');
+      const lightQuery = window.matchMedia('(prefers-color-scheme: light)');
+
+      if (darkQuery.matches) setTheme('dark');
+      else if (lightQuery.matches) setTheme('light');
+      else setTheme('no-preference');
+    };
+
+    mediaQuery.addEventListener('change', handleChange);
+
+    // Fallback: some environments may not fire change, so we also listen for light
+    const lightQuery = window.matchMedia('(prefers-color-scheme: light)');
+    lightQuery.addEventListener('change', updateTheme);
+
+    return () => {
+      mediaQuery.removeEventListener('change', handleChange);
+      lightQuery.removeEventListener('change', updateTheme);
+    };
+  }, []);
+
+  return theme;
+}

package/src/useWrappedChildren.ts

@@ -0,0 +1,58 @@
+import { ComponentChildren, cloneElement, isValidElement } from 'preact'
+import { useMemo } from 'preact/hooks'
+
+export type InjectableProps = Record<string, any>
+
+/**
+ * A Preact hook to wrap children components and inject additional props into them.
+ * @param children - The children to wrap and enhance with props.
+ * @param injectProps - The props to inject into each child component.
+ * @param mergeStrategy - How to handle prop conflicts ('override' | 'preserve'). Defaults to 'preserve'.
+ * @returns Enhanced children with injected props.
+ */
+export function useWrappedChildren(
+  children: ComponentChildren,
+  injectProps: InjectableProps,
+  mergeStrategy: 'override' | 'preserve' = 'preserve'
+): ComponentChildren {
+  return useMemo(() => {
+    if (!children) return children
+
+    const enhanceChild = (child: any): any => {
+      if (!isValidElement(child)) return child
+
+      const existingProps = child.props || {}
+      
+      let mergedProps: InjectableProps
+      
+      if (mergeStrategy === 'override') {
+        // Injected props override existing ones
+        mergedProps = { ...existingProps, ...injectProps }
+      } else {
+        // Existing props are preserved, injected props are added only if not present
+        mergedProps = { ...injectProps, ...existingProps }
+      }
+
+      // Special handling for style prop to merge style objects properly
+      const existingStyle = (existingProps as any)?.style
+      const injectStyle = (injectProps as any)?.style
+      
+      if (existingStyle && injectStyle && 
+          typeof existingStyle === 'object' && typeof injectStyle === 'object') {
+        if (mergeStrategy === 'override') {
+          (mergedProps as any).style = { ...existingStyle, ...injectStyle }
+        } else {
+          (mergedProps as any).style = { ...injectStyle, ...existingStyle }
+        }
+      }
+
+      return cloneElement(child, mergedProps)
+    }
+
+    if (Array.isArray(children)) {
+      return children.map(enhanceChild)
+    }
+
+    return enhanceChild(children)
+  }, [children, injectProps, mergeStrategy])
+}