chore: import upstream snapshot with attribution

surfsense_web/hooks/use-documents-processing.ts

@@ -0,0 +1,110 @@
+"use client";
+
+import { useQuery } from "@rocicorp/zero/react";
+import { useEffect, useRef, useState } from "react";
+import { queries } from "@/zero/queries";
+
+export type DocumentsProcessingStatus =
+	| "idle"
+	| "processing"
+	| "background_sync"
+	| "success"
+	| "error";
+
+const SUCCESS_LINGER_MS = 5000;
+
+interface UseDocumentsProcessingOptions {
+	hasPeriodicSyncEnabled?: boolean;
+}
+
+/**
+ * Returns the processing status of documents in the workspace:
+ *   - "processing"      — docs are queued or actively being prepared for search
+ *   - "background_sync" — existing docs are being refreshed in the background
+ *   - "error"      — nothing processing, but failed docs exist (show red icon)
+ *   - "success"    — just transitioned from processing → all clear (green check, auto-dismisses)
+ *   - "idle"       — nothing noteworthy (show normal icon)
+ */
+export function useDocumentsProcessing(
+	workspaceId: number | null,
+	{ hasPeriodicSyncEnabled = false }: UseDocumentsProcessingOptions = {}
+): DocumentsProcessingStatus {
+	const [status, setStatus] = useState<DocumentsProcessingStatus>("idle");
+	const wasProcessingRef = useRef(false);
+	const successTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+	const [documents] = useQuery(queries.documents.bySpace({ workspaceId: workspaceId ?? -1 }));
+
+	useEffect(() => {
+		if (!workspaceId || !documents) return;
+
+		const clearSuccessTimer = () => {
+			if (successTimerRef.current) {
+				clearTimeout(successTimerRef.current);
+				successTimerRef.current = null;
+			}
+		};
+
+		let pendingCount = 0;
+		let processingCount = 0;
+		let failedCount = 0;
+		let readyCount = 0;
+
+		for (const doc of documents) {
+			// Keep the nav indicator aligned with what the Documents sidebar actually renders.
+			// Some connectors can create temporary untitled placeholder rows that remain hidden
+			// from the sidebar, and those should not keep the whole section looking "stuck".
+			if (!doc.title || doc.title.trim() === "") {
+				continue;
+			}
+
+			const state = (doc.status as { state?: string } | null)?.state;
+			if (state === "pending") {
+				pendingCount++;
+			} else if (state === "processing") {
+				processingCount++;
+			} else if (state === "failed") {
+				failedCount++;
+			} else {
+				readyCount++;
+			}
+		}
+
+		if (pendingCount > 0) {
+			wasProcessingRef.current = true;
+			clearSuccessTimer();
+			setStatus("processing");
+		} else if (processingCount > 0) {
+			wasProcessingRef.current = true;
+			clearSuccessTimer();
+
+			const isBackgroundSync = hasPeriodicSyncEnabled && readyCount > 0;
+			setStatus(isBackgroundSync ? "background_sync" : "processing");
+		} else if (failedCount > 0) {
+			wasProcessingRef.current = false;
+			clearSuccessTimer();
+			setStatus("error");
+		} else if (wasProcessingRef.current) {
+			wasProcessingRef.current = false;
+			setStatus("success");
+			clearSuccessTimer();
+			successTimerRef.current = setTimeout(() => {
+				setStatus("idle");
+				successTimerRef.current = null;
+			}, SUCCESS_LINGER_MS);
+		} else {
+			setStatus("idle");
+		}
+	}, [workspaceId, documents, hasPeriodicSyncEnabled]);
+
+	useEffect(() => {
+		return () => {
+			if (successTimerRef.current) {
+				clearTimeout(successTimerRef.current);
+				successTimerRef.current = null;
+			}
+		};
+	}, []);
+
+	return status;
+}