preact-missing-hooks 3.1.0 → 4.1.0

package/src/useWebRTCIP.ts

@@ -1,176 +1,181 @@
-/**
- * useWebRTCIP – detect local/public IPs via WebRTC ICE candidates and STUN.
- * Not highly reliable; use as first-priority hint and fall back to a public IP API (e.g. ipapi.co) if needed.
- * @module useWebRTCIP
- */
-
-import { useEffect, useState, useRef } from 'preact/hooks';
-
-/** IPv4 regex for ICE candidate strings (captures dotted-decimal). */
-const IPV4_REGEX = /\b(?:25[0-5]|2[0-4]\d|1?\d{1,2})(?:\.(?:25[0-5]|2[0-4]\d|1?\d{1,2})){3}\b/g;
-
-const DEFAULT_STUN_SERVERS: string[] = ['stun:stun.l.google.com:19302'];
-const DEFAULT_TIMEOUT_MS = 3000;
-
-export interface UseWebRTCIPOptions {
-  /** STUN server URLs (default: Google STUN). */
-  stunServers?: string[];
-  /** Stop gathering after this many ms (default: 3000). */
-  timeout?: number;
-  /** Called once per newly detected IP (no duplicates). */
-  onDetect?: (ip: string) => void;
-}
-
-export interface UseWebRTCIPReturn {
-  /** Unique IPv4 addresses found from ICE candidates. */
-  ips: string[];
-  /** True while ICE gathering is in progress. */
-  loading: boolean;
-  /** Error message if WebRTC is unavailable or detection fails. */
-  error: string | null;
-}
-
-function isSSR(): boolean {
-  return typeof window === 'undefined';
-}
-
-function isWebRTCAvailable(): boolean {
-  return typeof RTCPeerConnection !== 'undefined';
-}
-
-/**
- * Extracts IPv4 addresses from an ICE candidate string.
- * Filters out common non-public/local patterns (e.g. 0.0.0.0) if desired; currently returns all matches.
- */
-function extractIPv4FromCandidate(candidate: string): string[] {
-  const matches = candidate.match(IPV4_REGEX);
-  return matches ? [...matches] : [];
-}
-
-/**
- * Attempts to detect client IP addresses using WebRTC ICE candidates and a STUN server.
- * Works frontend-only (no backend). Not guaranteed to return a public IP; use as a hint and
- * fall back to a public IP API (e.g. ipapi.co, ip-api.com) if you need reliability.
- *
- * @param options - Optional: stunServers, timeout (ms), onDetect(ip) callback.
- * @returns { ips, loading, error } – unique IPv4s, loading flag, and error message.
- *
- * @example
- * const { ips, loading, error } = useWebRTCIP({
- *   timeout: 5000,
- *   onDetect: (ip) => console.log('Detected:', ip),
- * })
- * // If ips is empty and error is set, fall back to: fetch('https://api.ipify.org?format=json')
- */
-export function useWebRTCIP(options: UseWebRTCIPOptions = {}): UseWebRTCIPReturn {
-  const {
-    stunServers = DEFAULT_STUN_SERVERS,
-    timeout: timeoutMs = DEFAULT_TIMEOUT_MS,
-    onDetect,
-  } = options;
-
-  const [ips, setIps] = useState<string[]>([]);
-  const [loading, setLoading] = useState(true);
-  const [error, setError] = useState<string | null>(null);
-
-  const pcRef = useRef<RTCPeerConnection | null>(null);
-  const timeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
-  const reportedRef = useRef<Set<string>>(new Set());
-  const onDetectRef = useRef(onDetect);
-  onDetectRef.current = onDetect;
-
-  useEffect(() => {
-    if (isSSR()) {
-      setLoading(false);
-      setError('WebRTC IP detection is not available during SSR');
-      return;
-    }
-
-    if (!isWebRTCAvailable()) {
-      setLoading(false);
-      setError('RTCPeerConnection is not available');
-      return;
-    }
-
-    const reported = new Set<string>();
-    reportedRef.current = reported;
-
-    const finish = () => {
-      if (timeoutRef.current) {
-        clearTimeout(timeoutRef.current);
-        timeoutRef.current = null;
-      }
-      if (pcRef.current) {
-        pcRef.current.close();
-        pcRef.current = null;
-      }
-      setLoading(false);
-    };
-
-    const addIP = (ip: string) => {
-      if (reported.has(ip)) return;
-      reported.add(ip);
-      setIps((prev) => {
-        const next = [...prev, ip];
-        return next;
-      });
-      onDetectRef.current?.(ip);
-    };
-
-    try {
-      const pc = new RTCPeerConnection({
-        iceServers: [{ urls: stunServers }],
-      });
-      pcRef.current = pc;
-
-      pc.onicecandidate = (event) => {
-        const c = event.candidate;
-        if (!c || !c.candidate) return;
-        const found = extractIPv4FromCandidate(c.candidate);
-        found.forEach(addIP);
-      };
-
-      pc.createDataChannel('');
-
-      pc.createOffer()
-        .then((offer) => pc.setLocalDescription(offer))
-        .catch((err) => {
-          setError(err instanceof Error ? err.message : 'Failed to create offer');
-          finish();
-        });
-
-      timeoutRef.current = setTimeout(() => finish(), timeoutMs);
-    } catch (err) {
-      setError(err instanceof Error ? err.message : 'WebRTC setup failed');
-      finish();
-    }
-
-    return () => {
-      finish();
-    };
-  }, [stunServers.join(','), timeoutMs]);
-
-  return { ips, loading, error };
-}
-
-/*
- * Example usage (Preact component):
- *
- * function MyIPDisplay() {
- *   const { ips, loading, error } = useWebRTCIP({
- *     timeout: 4000,
- *     onDetect: (ip) => { / * optional: e.g. send to analytics * / },
- *   })
- *
- *   if (loading) return <p>Detecting IP…</p>
- *   if (error) return <p>WebRTC failed: {error}. Try fallback API.</p>
- *   return <p>IPs (WebRTC): {ips.join(', ') || 'None'}</p>
- * }
- *
- * Fallback to public IP API when WebRTC fails or returns empty:
- *   const [apiIP, setApiIP] = useState<string | null>(null)
- *   useEffect(() => {
- *     if (!loading && ips.length === 0 && error)
- *       fetch('https://api.ipify.org?format=json').then(r => r.json()).then(d => setApiIP(d.ip))
- *   }, [loading, ips.length, error])
- */
+/**
+ * useWebRTCIP – detect local/public IPs via WebRTC ICE candidates and STUN.
+ * Not highly reliable; use as first-priority hint and fall back to a public IP API (e.g. ipapi.co) if needed.
+ * @module useWebRTCIP
+ */
+
+import { useEffect, useState, useRef } from "preact/hooks";
+
+/** IPv4 regex for ICE candidate strings (captures dotted-decimal). */
+const IPV4_REGEX =
+  /\b(?:25[0-5]|2[0-4]\d|1?\d{1,2})(?:\.(?:25[0-5]|2[0-4]\d|1?\d{1,2})){3}\b/g;
+
+const DEFAULT_STUN_SERVERS: string[] = ["stun:stun.l.google.com:19302"];
+const DEFAULT_TIMEOUT_MS = 3000;
+
+export interface UseWebRTCIPOptions {
+  /** STUN server URLs (default: Google STUN). */
+  stunServers?: string[];
+  /** Stop gathering after this many ms (default: 3000). */
+  timeout?: number;
+  /** Called once per newly detected IP (no duplicates). */
+  onDetect?: (ip: string) => void;
+}
+
+export interface UseWebRTCIPReturn {
+  /** Unique IPv4 addresses found from ICE candidates. */
+  ips: string[];
+  /** True while ICE gathering is in progress. */
+  loading: boolean;
+  /** Error message if WebRTC is unavailable or detection fails. */
+  error: string | null;
+}
+
+function isSSR(): boolean {
+  return typeof window === "undefined";
+}
+
+function isWebRTCAvailable(): boolean {
+  return typeof RTCPeerConnection !== "undefined";
+}
+
+/**
+ * Extracts IPv4 addresses from an ICE candidate string.
+ * Filters out common non-public/local patterns (e.g. 0.0.0.0) if desired; currently returns all matches.
+ */
+function extractIPv4FromCandidate(candidate: string): string[] {
+  const matches = candidate.match(IPV4_REGEX);
+  return matches ? [...matches] : [];
+}
+
+/**
+ * Attempts to detect client IP addresses using WebRTC ICE candidates and a STUN server.
+ * Works frontend-only (no backend). Not guaranteed to return a public IP; use as a hint and
+ * fall back to a public IP API (e.g. ipapi.co, ip-api.com) if you need reliability.
+ *
+ * @param options - Optional: stunServers, timeout (ms), onDetect(ip) callback.
+ * @returns { ips, loading, error } – unique IPv4s, loading flag, and error message.
+ *
+ * @example
+ * const { ips, loading, error } = useWebRTCIP({
+ *   timeout: 5000,
+ *   onDetect: (ip) => console.log('Detected:', ip),
+ * })
+ * // If ips is empty and error is set, fall back to: fetch('https://api.ipify.org?format=json')
+ */
+export function useWebRTCIP(
+  options: UseWebRTCIPOptions = {}
+): UseWebRTCIPReturn {
+  const {
+    stunServers = DEFAULT_STUN_SERVERS,
+    timeout: timeoutMs = DEFAULT_TIMEOUT_MS,
+    onDetect,
+  } = options;
+
+  const [ips, setIps] = useState<string[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  const pcRef = useRef<RTCPeerConnection | null>(null);
+  const timeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const reportedRef = useRef<Set<string>>(new Set());
+  const onDetectRef = useRef(onDetect);
+  onDetectRef.current = onDetect;
+
+  useEffect(() => {
+    if (isSSR()) {
+      setLoading(false);
+      setError("WebRTC IP detection is not available during SSR");
+      return;
+    }
+
+    if (!isWebRTCAvailable()) {
+      setLoading(false);
+      setError("RTCPeerConnection is not available");
+      return;
+    }
+
+    const reported = new Set<string>();
+    reportedRef.current = reported;
+
+    const finish = () => {
+      if (timeoutRef.current) {
+        clearTimeout(timeoutRef.current);
+        timeoutRef.current = null;
+      }
+      if (pcRef.current) {
+        pcRef.current.close();
+        pcRef.current = null;
+      }
+      setLoading(false);
+    };
+
+    const addIP = (ip: string) => {
+      if (reported.has(ip)) return;
+      reported.add(ip);
+      setIps((prev) => {
+        const next = [...prev, ip];
+        return next;
+      });
+      onDetectRef.current?.(ip);
+    };
+
+    try {
+      const pc = new RTCPeerConnection({
+        iceServers: [{ urls: stunServers }],
+      });
+      pcRef.current = pc;
+
+      pc.onicecandidate = (event) => {
+        const c = event.candidate;
+        if (!c || !c.candidate) return;
+        const found = extractIPv4FromCandidate(c.candidate);
+        found.forEach(addIP);
+      };
+
+      pc.createDataChannel("");
+
+      pc.createOffer()
+        .then((offer) => pc.setLocalDescription(offer))
+        .catch((err) => {
+          setError(
+            err instanceof Error ? err.message : "Failed to create offer"
+          );
+          finish();
+        });
+
+      timeoutRef.current = setTimeout(() => finish(), timeoutMs);
+    } catch (err) {
+      setError(err instanceof Error ? err.message : "WebRTC setup failed");
+      finish();
+    }
+
+    return () => {
+      finish();
+    };
+  }, [stunServers.join(","), timeoutMs]);
+
+  return { ips, loading, error };
+}
+
+/*
+ * Example usage (Preact component):
+ *
+ * function MyIPDisplay() {
+ *   const { ips, loading, error } = useWebRTCIP({
+ *     timeout: 4000,
+ *     onDetect: (ip) => { / * optional: e.g. send to analytics * / },
+ *   })
+ *
+ *   if (loading) return <p>Detecting IP…</p>
+ *   if (error) return <p>WebRTC failed: {error}. Try fallback API.</p>
+ *   return <p>IPs (WebRTC): {ips.join(', ') || 'None'}</p>
+ * }
+ *
+ * Fallback to public IP API when WebRTC fails or returns empty:
+ *   const [apiIP, setApiIP] = useState<string | null>(null)
+ *   useEffect(() => {
+ *     if (!loading && ips.length === 0 && error)
+ *       fetch('https://api.ipify.org?format=json').then(r => r.json()).then(d => setApiIP(d.ip))
+ *   }, [loading, ips.length, error])
+ */

package/src/useWorkerNotifications.ts

@@ -3,10 +3,14 @@
  * @module useWorkerNotifications
  */
 
-import { useState, useRef, useEffect, useMemo } from 'preact/hooks';
+import { useState, useRef, useEffect, useMemo } from "preact/hooks";
 
 /** Supported worker event types for tracking. Worker should postMessage with these shapes. */
-export type WorkerEventType = 'task_start' | 'task_end' | 'task_fail' | 'queue_size';
+export type WorkerEventType =
+  | "task_start"
+  | "task_end"
+  | "task_fail"
+  | "queue_size";
 
 export interface WorkerNotificationEvent {
   type: WorkerEventType;
@@ -53,21 +57,21 @@ export interface UseWorkerNotificationsReturn {
 }
 
 function parseMessage(data: unknown): WorkerNotificationEvent | null {
-  if (data == null || typeof data !== 'object') return null;
+  if (data == null || typeof data !== "object") return null;
   const d = data as Record<string, unknown>;
   const type = d.type as string;
   if (
-    type !== 'task_start' &&
-    type !== 'task_end' &&
-    type !== 'task_fail' &&
-    type !== 'queue_size'
+    type !== "task_start" &&
+    type !== "task_end" &&
+    type !== "task_fail" &&
+    type !== "queue_size"
   ) {
     return null;
   }
-  const taskId = typeof d.taskId === 'string' ? d.taskId : undefined;
-  const duration = typeof d.duration === 'number' ? d.duration : undefined;
-  const error = typeof d.error === 'string' ? d.error : undefined;
-  const size = typeof d.size === 'number' ? d.size : undefined;
+  const taskId = typeof d.taskId === "string" ? d.taskId : undefined;
+  const duration = typeof d.duration === "number" ? d.duration : undefined;
+  const error = typeof d.error === "string" ? d.error : undefined;
+  const size = typeof d.size === "number" ? d.size : undefined;
   return {
     type: type as WorkerEventType,
     taskId,
@@ -96,7 +100,9 @@ export function useWorkerNotifications(
   const [runningTasks, setRunningTasks] = useState<string[]>([]);
   const [completedCount, setCompletedCount] = useState(0);
   const [failedCount, setFailedCount] = useState(0);
-  const [eventHistory, setEventHistory] = useState<WorkerNotificationEvent[]>([]);
+  const [eventHistory, setEventHistory] = useState<WorkerNotificationEvent[]>(
+    []
+  );
   const [currentQueueSize, setCurrentQueueSize] = useState(0);
 
   const completedTimestampsRef = useRef<number[]>([]);
@@ -115,11 +121,11 @@ export function useWorkerNotifications(
         return next;
       });
 
-      if (ev.type === 'task_start' && ev.taskId) {
+      if (ev.type === "task_start" && ev.taskId) {
         setRunningTasks((prev) =>
           prev.includes(ev.taskId!) ? prev : [...prev, ev.taskId!]
         );
-      } else if (ev.type === 'task_end') {
+      } else if (ev.type === "task_end") {
         if (ev.taskId) {
           setRunningTasks((prev) => prev.filter((id) => id !== ev.taskId));
         }
@@ -129,22 +135,22 @@ export function useWorkerNotifications(
           ...completedTimestampsRef.current.filter((t) => t >= cutoff),
           ev.timestamp,
         ];
-        if (typeof ev.duration === 'number') {
+        if (typeof ev.duration === "number") {
           durationSumRef.current += ev.duration;
           durationCountRef.current += 1;
         }
-      } else if (ev.type === 'task_fail') {
+      } else if (ev.type === "task_fail") {
         if (ev.taskId) {
           setRunningTasks((prev) => prev.filter((id) => id !== ev.taskId));
         }
         setFailedCount((c) => c + 1);
-      } else if (ev.type === 'queue_size' && typeof ev.size === 'number') {
+      } else if (ev.type === "queue_size" && typeof ev.size === "number") {
         setCurrentQueueSize(ev.size);
       }
     };
 
-    worker.addEventListener('message', onMessage);
-    return () => worker.removeEventListener('message', onMessage);
+    worker.addEventListener("message", onMessage);
+    return () => worker.removeEventListener("message", onMessage);
   }, [worker, maxHistory]);
 
   const averageDurationMs = useMemo(() => {
@@ -156,7 +162,9 @@ export function useWorkerNotifications(
   const throughputPerSecond = useMemo(() => {
     const now = Date.now();
     const cutoff = now - throughputWindowMs;
-    const timestamps = completedTimestampsRef.current.filter((t) => t >= cutoff);
+    const timestamps = completedTimestampsRef.current.filter(
+      (t) => t >= cutoff
+    );
     return timestamps.length / (throughputWindowMs / 1000);
   }, [eventHistory, throughputWindowMs]);
 

package/src/useWrappedChildren.ts

@@ -1,58 +1,72 @@
-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])
-}
+import { ComponentChildren, cloneElement, isValidElement, VNode } from "preact";
+import { useMemo } from "preact/hooks";
+
+export type InjectableProps = Record<string, unknown>;
+
+interface PropsWithStyle {
+  style?: Record<string, string | number>;
+}
+
+/**
+ * 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: ComponentChildren): ComponentChildren => {
+      if (!isValidElement(child)) return child;
+
+      const existingProps = (child as VNode).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 PropsWithStyle)?.style;
+      const injectStyle = (injectProps as PropsWithStyle)?.style;
+
+      if (
+        existingStyle &&
+        injectStyle &&
+        typeof existingStyle === "object" &&
+        typeof injectStyle === "object"
+      ) {
+        if (mergeStrategy === "override") {
+          (mergedProps as PropsWithStyle).style = {
+            ...existingStyle,
+            ...injectStyle,
+          };
+        } else {
+          (mergedProps as PropsWithStyle).style = {
+            ...injectStyle,
+            ...existingStyle,
+          };
+        }
+      }
+
+      return cloneElement(child, mergedProps);
+    };
+
+    if (Array.isArray(children)) {
+      return children.map(enhanceChild);
+    }
+
+    return enhanceChild(children);
+  }, [children, injectProps, mergeStrategy]);
+}

package/tests/preact-as-react.ts

@@ -0,0 +1,5 @@
+/**
+ * Re-exports Preact hooks as "react" for tests so useLLMMetadata (which imports from "react")
+ * uses the same renderer as the Preact test components.
+ */
+export { useEffect, useRef } from "preact/hooks";

package/tests/react-adapter.tsx

@@ -0,0 +1,12 @@
+/**
+ * Adapter so the same test files can run with React: provides Preact-like exports.
+ * Used when running tests with the "react" Vitest project (alias preact → this file).
+ */
+import * as React from "react";
+
+export const h = React.createElement;
+export const cloneElement = React.cloneElement;
+export const isValidElement = React.isValidElement;
+export type ComponentChildren = React.ReactNode;
+export type RefObject<T> = React.RefObject<T>;
+export type VNode = React.ReactElement;

package/tests/setup-react.ts

@@ -0,0 +1,4 @@
+/**
+ * Setup for React Vitest project. Ensures tests can detect they run under React.
+ */
+(globalThis as unknown as { __VITEST_REACT__?: boolean }).__VITEST_REACT__ = true;