JsDoc across all project files

src/client/components/App.tsx

@@ -1,3 +1,10 @@
+/**
+ * @fileoverview Root application component.
+ * Provides the main layout structure with navigation, content outlet,
+ * and toast notifications. Initializes socket connection on mount.
+ * @module components/App
+ */
+
 import React, { ReactElement, useEffect } from "react";
 import { Outlet } from "react-router-dom";
 import { Navbar2 } from "./shared/Navbar2";
@@ -5,6 +12,26 @@ import { ToastContainer } from "react-toastify";
 import "../../app.css";
 import { useStore } from "../store";
 
+/**
+ * Root application component that provides the main layout structure.
+ *
+ * Features:
+ * - Initializes WebSocket connection to the server on mount
+ * - Renders the navigation bar across all routes
+ * - Provides React Router outlet for child routes
+ * - Includes toast notification container for app-wide notifications
+ *
+ * @returns {ReactElement} The root application layout
+ * @example
+ * // Used as the root element in React Router configuration
+ * const router = createBrowserRouter([
+ *   {
+ *     path: "/",
+ *     element: <App />,
+ *     children: [...]
+ *   }
+ * ]);
+ */
 export const App = (): ReactElement => {
   useEffect(() => {
     useStore.getState().getSocket("/"); // Connect to the base namespace

src/client/components/Import/Import.tsx

@@ -1,3 +1,10 @@
+/**
+ * @fileoverview Import page component for managing comic library imports.
+ * Provides UI for starting imports, monitoring progress, viewing history,
+ * and handling directory configuration issues.
+ * @module components/Import/Import
+ */
+
 import { ReactElement, useEffect, useRef, useState } from "react";
 import { format } from "date-fns";
 import { isEmpty } from "lodash";
@@ -10,16 +17,40 @@ import { RealTimeImportStats } from "./RealTimeImportStats";
 import { useImportSessionStatus } from "../../hooks/useImportSessionStatus";
 import { SETTINGS_SERVICE_BASE_URI } from "../../constants/endpoints";
 
+/**
+ * Represents an issue with a configured directory.
+ * @interface DirectoryIssue
+ * @property {string} directory - Path to the directory with issues
+ * @property {string} issue - Description of the issue
+ */
 interface DirectoryIssue {
   directory: string;
   issue: string;
 }
 
+/**
+ * Result of directory status check from the backend.
+ * @interface DirectoryStatus
+ * @property {boolean} isValid - Whether all required directories are accessible
+ * @property {DirectoryIssue[]} issues - List of specific issues found
+ */
 interface DirectoryStatus {
   isValid: boolean;
   issues: DirectoryIssue[];
 }
 
+/**
+ * Import page component for managing comic library imports.
+ *
+ * Features:
+ * - Real-time import progress tracking via WebSocket
+ * - Directory status validation before import
+ * - Force re-import functionality for fixing indexing issues
+ * - Past import history table
+ * - Session management for import tracking
+ *
+ * @returns {ReactElement} The import page UI
+ */
 export const Import = (): ReactElement => {
   const [importError, setImportError] = useState<string | null>(null);
   const queryClient = useQueryClient();

src/client/components/Import/RealTimeImportStats.tsx

@@ -1,3 +1,10 @@
+/**
+ * @fileoverview Real-time import statistics component with live progress tracking.
+ * Displays import statistics, progress bars, and file detection notifications
+ * using WebSocket events for real-time updates.
+ * @module components/Import/RealTimeImportStats
+ */
+
 import { ReactElement, useState } from "react";
 import { Link } from "react-router-dom";
 import {
@@ -15,7 +22,7 @@ import { StatsCard } from "../shared/StatsCard";
 import { ProgressBar } from "../shared/ProgressBar";
 
 /**
- * RealTimeImportStats component displays import statistics with a card-based layout and progress bar.
+ * Real-time import statistics component with card-based layout and progress tracking.
  *
  * This component manages three distinct states:
  * - **Pre-import (idle)**: Shows current file counts and "Start Import" button when new files exist

src/client/components/shared/AlertCard.tsx

@@ -1,5 +1,16 @@
+/**
+ * @fileoverview Reusable alert card component for displaying status messages.
+ * Supports multiple variants (error, warning, info, success) with consistent
+ * styling and optional dismiss functionality.
+ * @module components/shared/AlertCard
+ */
+
 import { ReactElement, ReactNode } from "react";
 
+/**
+ * Visual style variants for the alert card.
+ * @typedef {"error"|"warning"|"info"|"success"} AlertVariant
+ */
 export type AlertVariant = "error" | "warning" | "info" | "success";
 
 interface AlertCardProps {

src/client/components/shared/ProgressBar.tsx

@@ -1,5 +1,15 @@
+/**
+ * @fileoverview Reusable progress bar component with percentage display.
+ * Supports animated shimmer effect for active states and customizable labels.
+ * @module components/shared/ProgressBar
+ */
+
 import { ReactElement } from "react";
 
+/**
+ * Props for the ProgressBar component.
+ * @interface ProgressBarProps
+ */
 interface ProgressBarProps {
   /** Current progress value */
   current: number;

src/client/components/shared/StatsCard.tsx

@@ -1,5 +1,15 @@
+/**
+ * @fileoverview Reusable stats card component for displaying numeric metrics.
+ * Used for dashboards and import statistics displays.
+ * @module components/shared/StatsCard
+ */
+
 import { ReactElement } from "react";
 
+/**
+ * Props for the StatsCard component.
+ * @interface StatsCardProps
+ */
 interface StatsCardProps {
   /** The main numeric value to display */
   value: number;