Refactor useHistory hook: replace HistoryQuery with explicit parameters and add documentation

- Split useHistory interface to accept explicit parameters (page, pageSize, range, origin, jail, ip, source) instead of HistoryQuery object
- Add comprehensive JSDoc for useHistory function
- Update HistoryPage and tests to use new parameter structure
- Move TaskList documentation from Tasks.md to Web-Development.md
- Improve type safety with explicit TimeRange and BanOriginFilter types

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

frontend/src/hooks/useHistory.ts

@@ -5,11 +5,8 @@
 import { useCallback, useEffect, useRef, useState } from "react";
 import { fetchHistory, fetchIpHistory } from "../api/history";
 import { handleFetchError } from "../utils/fetchError";
-import type {
-  HistoryBanItem,
-  HistoryQuery,
-  IpDetailResponse,
-} from "../types/history";
+import type { HistoryBanItem, IpDetailResponse } from "../types/history";
+import type { BanOriginFilter, TimeRange } from "../types/ban";
 
 // ---------------------------------------------------------------------------
 // useHistory — paginated list
@@ -25,10 +22,30 @@ export interface UseHistoryResult {
   refresh: () => void;
 }
 
-export function useHistory(query: HistoryQuery = {}): UseHistoryResult {
+/**
+ * Fetch and manage paginated ban history with optional filters.
+ *
+ * @param page - Current page number (1-indexed)
+ * @param pageSize - Items per page
+ * @param range - Time range filter (e.g., "7d", "30d")
+ * @param origin - Ban origin filter (e.g., "fail2ban", "blocklist")
+ * @param jail - Jail name filter (optional)
+ * @param ip - IP address filter (optional)
+ * @param source - Data source ("fail2ban" | "archive")
+ * @returns History data with pagination and error state
+ */
+export function useHistory(
+  page: number = 1,
+  pageSize: number = 50,
+  range?: TimeRange,
+  origin?: BanOriginFilter,
+  jail?: string,
+  ip?: string,
+  source: "fail2ban" | "archive" = "archive",
+): UseHistoryResult {
   const [items, setItems] = useState<HistoryBanItem[]>([]);
   const [total, setTotal] = useState(0);
-  const [page, setPage] = useState(query.page ?? 1);
+  const [currentPage, setCurrentPage] = useState(page);
   const [loading, setLoading] = useState(true);
   const [error, setError] = useState<string | null>(null);
   const abortRef = useRef<AbortController | null>(null);
@@ -39,7 +56,18 @@ export function useHistory(query: HistoryQuery = {}): UseHistoryResult {
     setLoading(true);
     setError(null);
 
-    fetchHistory({ ...query, page }, abortRef.current.signal)
+    fetchHistory(
+      {
+        page: currentPage,
+        page_size: pageSize,
+        range,
+        origin,
+        jail,
+        ip,
+        source,
+      },
+      abortRef.current.signal,
+    )
       .then((resp) => {
         setItems(resp.items);
         setTotal(resp.total);
@@ -50,7 +78,8 @@ export function useHistory(query: HistoryQuery = {}): UseHistoryResult {
       .finally((): void => {
         setLoading(false);
       });
-  }, [query, page]);
+  }, [currentPage, pageSize, range, origin, jail, ip, source]);
+
 
   useEffect((): (() => void) => {
     load();
@@ -59,7 +88,15 @@ export function useHistory(query: HistoryQuery = {}): UseHistoryResult {
     };
   }, [load]);
 
-  return { items, total, page, loading, error, setPage, refresh: load };
+  return {
+    items,
+    total,
+    page: currentPage,
+    loading,
+    error,
+    setPage: setCurrentPage,
+    refresh: load,
+  };
 }
 
 // ---------------------------------------------------------------------------