feat(frontend): add config hooks for jail, action, filter, and auto-save

- useJailFileConfig: manages jail.local section state with dirty tracking - useActionConfig: manages action .conf file state - useFilterConfig: manages filter .conf file state - useAutoSave: debounced auto-save with status indicator support
2026-03-13 13:47:55 +01:00
parent 8bdad3529f
commit a0e8566ff8
4 changed files with 375 additions and 0 deletions
--- a/frontend/src/hooks/useAutoSave.ts
+++ b/frontend/src/hooks/useAutoSave.ts
@@ -0,0 +1,119 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+
+export type AutoSaveStatus = "idle" | "saving" | "saved" | "error";
+
+interface UseAutoSaveOptions<T> {
+  /** Debounce delay in ms. Default: 800. */
+  debounceMs?: number;
+  /** Equality check. Default: JSON.stringify comparison. */
+  isEqual?: (a: T, b: T) => boolean;
+}
+
+interface UseAutoSaveResult {
+  status: AutoSaveStatus;
+  errorText: string | null;
+  retry: () => void;
+}
+
+const defaultIsEqual = <T>(a: T, b: T): boolean =>
+  JSON.stringify(a) === JSON.stringify(b);
+
+export function useAutoSave<T>(
+  value: T,
+  save: (value: T) => Promise<void>,
+  options?: UseAutoSaveOptions<T>,
+): UseAutoSaveResult {
+  const [status, setStatus] = useState<AutoSaveStatus>("idle");
+  const [errorText, setErrorText] = useState<string | null>(null);
+
+  // Refs to avoid stale closures — option refs are intentionally NOT in deps.
+  const debounceRef = useRef(options?.debounceMs ?? 800);
+  const isEqualRef = useRef<(a: T, b: T) => boolean>(
+    options?.isEqual ?? defaultIsEqual,
+  );
+  const savedValueRef = useRef<T>(value);
+  const latestValueRef = useRef<T>(value);
+  const isSavingRef = useRef<boolean>(false);
+  const pendingSaveRef = useRef<boolean>(false);
+  const debounceTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const savedTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const saveRef = useRef(save);
+
+  // Keep mutable refs up to date without triggering effects.
+  saveRef.current = save;
+  latestValueRef.current = value;
+
+  const performSave = useCallback(async (valueToSave: T): Promise<void> => {
+    if (isSavingRef.current) {
+      pendingSaveRef.current = true;
+      return;
+    }
+
+    isSavingRef.current = true;
+    pendingSaveRef.current = false;
+    setStatus("saving");
+    setErrorText(null);
+
+    try {
+      await saveRef.current(valueToSave);
+      savedValueRef.current = valueToSave;
+      setStatus("saved");
+
+      if (savedTimerRef.current !== null) {
+        clearTimeout(savedTimerRef.current);
+      }
+      savedTimerRef.current = setTimeout(() => {
+        setStatus("idle");
+        savedTimerRef.current = null;
+      }, 2000);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      setErrorText(msg);
+      setStatus("error");
+    } finally {
+      isSavingRef.current = false;
+
+      // If a pending save was queued while we were saving, run it now.
+      if (pendingSaveRef.current as boolean) {
+        pendingSaveRef.current = false;
+        await performSave(latestValueRef.current);
+      }
+    }
+  }, []);
+
+  // Debounce on value change. Only `value` and the stable `performSave` are
+  // deps — option refs are read directly to avoid re-running the effect when
+  // the caller recreates option callbacks.
+  useEffect(() => {
+    if (isEqualRef.current(value, savedValueRef.current)) {
+      return;
+    }
+
+    if (debounceTimerRef.current !== null) {
+      clearTimeout(debounceTimerRef.current);
+    }
+
+    debounceTimerRef.current = setTimeout(() => {
+      debounceTimerRef.current = null;
+      void performSave(latestValueRef.current);
+    }, debounceRef.current);
+  }, [value, performSave]);
+
+  // Cleanup timers on unmount.
+  useEffect(() => {
+    return (): void => {
+      if (debounceTimerRef.current !== null) {
+        clearTimeout(debounceTimerRef.current);
+      }
+      if (savedTimerRef.current !== null) {
+        clearTimeout(savedTimerRef.current);
+      }
+    };
+  }, []);
+
+  const retry = useCallback(() => {
+    void performSave(latestValueRef.current);
+  }, [performSave]);
+
+  return { status, errorText, retry };
+}