@rxtx4816/cockpit-plugin-base-react 1.0.0

package/src/hooks/useAsyncAction.ts

@@ -0,0 +1,31 @@
+import { useState, useCallback } from "react";
+
+export function useAsyncAction<T>(
+  action: () => Promise<T>,
+): {
+  execute: () => Promise<T | undefined>;
+  loading: boolean;
+  error: string | null;
+  clearError: () => void;
+} {
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const clearError = useCallback(() => setError(null), []);
+
+  const execute = useCallback(async (): Promise<T | undefined> => {
+    setLoading(true);
+    setError(null);
+    try {
+      const result = await action();
+      return result;
+    } catch (ex: unknown) {
+      setError(ex instanceof Error ? ex.message : String(ex));
+      return undefined;
+    } finally {
+      setLoading(false);
+    }
+  }, [action]);
+
+  return { execute, loading, error, clearError };
+}

package/src/hooks/useAsyncStream.test.ts

@@ -0,0 +1,122 @@
+import { renderHook, act, waitFor } from "@testing-library/react";
+import { describe, it, expect, vi } from "vitest";
+import { useAsyncStream } from "./useAsyncStream";
+import { mockProcess } from "../testing/helpers";
+
+function mockRunningProcess(initialData: string): CockpitProcess {
+  let streamCb: ((data: string) => void) | null = null;
+  const p = new Promise<string>(() => {}); // never resolves — process stays "running"
+  queueMicrotask(() => { if (streamCb) streamCb(initialData); });
+  return Object.assign(p, {
+    stream: (cb: (data: string) => void) => { streamCb = cb; return p as CockpitProcess; },
+    close: vi.fn(),
+    input: vi.fn(),
+    wait: () => p,
+  }) as CockpitProcess;
+}
+
+describe("useAsyncStream", () => {
+  it("accumulates lines from streamed output", async () => {
+    const { result } = renderHook(() =>
+      useAsyncStream(async launch => {
+        launch(mockProcess("line1\nline2\nline3\n"));
+      }, []),
+    );
+
+    await waitFor(() => expect(result.current.done).toBe(true));
+    expect(result.current.lines).toEqual(["line1", "line2", "line3"]);
+    expect(result.current.failed).toBe(false);
+  });
+
+  it("handles multi-chunk output", async () => {
+    const { result } = renderHook(() =>
+      useAsyncStream(async launch => {
+        launch(mockProcess(["hello\n", "world\n"]));
+      }, []),
+    );
+
+    await waitFor(() => expect(result.current.done).toBe(true));
+    expect(result.current.lines).toEqual(["hello", "world"]);
+  });
+
+  it("handles \\r overwrite sequences by taking the last content on a line", async () => {
+    // \r without \n: "loading...\rprogress: 50%" on a single logical line
+    const { result } = renderHook(() =>
+      useAsyncStream(async launch => {
+        launch(mockProcess("loading...\rprogress: 50%\n"));
+      }, []),
+    );
+
+    await waitFor(() => expect(result.current.done).toBe(true));
+    expect(result.current.lines).toEqual(["progress: 50%"]);
+  });
+
+  it("sets failed and errorMsg on process error", async () => {
+    const { result } = renderHook(() =>
+      useAsyncStream(async launch => {
+        launch(mockProcess("partial\n", "process failed"));
+      }, []),
+    );
+
+    await waitFor(() => expect(result.current.done).toBe(true));
+    expect(result.current.failed).toBe(true);
+    expect(result.current.errorMsg).toBe("process failed");
+  });
+
+  it("sets failed when startProcess itself throws", async () => {
+    const { result } = renderHook(() =>
+      useAsyncStream(async () => {
+        throw new Error("launch error");
+      }, []),
+    );
+
+    await waitFor(() => expect(result.current.done).toBe(true));
+    expect(result.current.failed).toBe(true);
+    expect(result.current.errorMsg).toBe("launch error");
+  });
+
+  it("starts empty and not done", () => {
+    const { result } = renderHook(() =>
+      useAsyncStream(async launch => {
+        launch(mockRunningProcess(""));
+      }, []),
+    );
+    expect(result.current.lines).toHaveLength(0);
+    expect(result.current.done).toBe(false);
+  });
+
+  it("cancel() closes the running process", async () => {
+    let capturedProc!: CockpitProcess;
+    const { result } = renderHook(() =>
+      useAsyncStream(async launch => {
+        capturedProc = mockRunningProcess("line1\n");
+        launch(capturedProc);
+      }, []),
+    );
+
+    await waitFor(() => expect(result.current.lines).toHaveLength(1));
+    act(() => { result.current.cancel(); });
+    expect(capturedProc.close).toHaveBeenCalled();
+  });
+
+  it("resets state when deps change", async () => {
+    let dep = 1;
+    const { result, rerender } = renderHook(() =>
+      useAsyncStream(async launch => {
+        launch(mockProcess("line\n"));
+      }, [dep]),
+    );
+
+    await waitFor(() => expect(result.current.done).toBe(true));
+    expect(result.current.lines).toHaveLength(1);
+
+    dep = 2;
+    rerender();
+
+    expect(result.current.lines).toHaveLength(0);
+    expect(result.current.done).toBe(false);
+
+    await waitFor(() => expect(result.current.done).toBe(true));
+    expect(result.current.lines).toHaveLength(1);
+  });
+});

package/src/hooks/useAsyncStream.ts

@@ -0,0 +1,94 @@
+import { useState, useEffect, useRef, useCallback } from "react";
+
+export interface AsyncStreamResult {
+  lines: string[];
+  done: boolean;
+  failed: boolean;
+  errorMsg: string;
+  cancel: () => void;
+}
+
+/**
+ * Generic hook for accumulating line-buffered output from a CockpitProcess.
+ *
+ * The caller supplies a `startProcess` factory that receives a `launch` callback.
+ * Call `launch(proc)` synchronously once the process is ready — this avoids the
+ * JS Promise "following" behaviour that occurs when a CockpitProcess (which extends
+ * Promise) is returned from inside a .then().
+ *
+ * The `deps` array works like useEffect deps — the hook tears down and restarts
+ * the process whenever any dep changes.
+ */
+export function useAsyncStream(
+  startProcess: (launch: (proc: CockpitProcess) => void) => Promise<void>,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  deps: any[],
+): AsyncStreamResult {
+  const [lines, setLines] = useState<string[]>([]);
+  const [done, setDone] = useState(false);
+  const [failed, setFailed] = useState(false);
+  const [errorMsg, setErrorMsg] = useState("");
+  const bufRef = useRef("");
+  const procRef = useRef<CockpitProcess | null>(null);
+
+  useEffect(() => {
+    let cancelled = false;
+    bufRef.current = "";
+    setLines([]);
+    setDone(false);
+    setFailed(false);
+    setErrorMsg("");
+
+    const launch = (proc: CockpitProcess) => {
+      if (cancelled) { proc.close(); return; }
+      procRef.current = proc;
+
+      proc.stream(data => {
+        bufRef.current += data;
+        const parts = bufRef.current.split("\n");
+        bufRef.current = parts.pop() ?? "";
+        const newLines = parts
+          .map(line => line.split("\r").pop() ?? "")
+          .filter(line => line.trim() !== "");
+        if (newLines.length > 0) {
+          setLines(prev => [...prev, ...newLines]);
+        }
+      });
+
+      proc
+        .then(() => {
+          if (!cancelled) { setDone(true); setFailed(false); }
+          procRef.current = null;
+        })
+        .catch((ex: unknown) => {
+          if (!cancelled) {
+            setDone(true);
+            setFailed(true);
+            setErrorMsg(ex instanceof Error ? ex.message : String(ex));
+          }
+          procRef.current = null;
+        });
+    };
+
+    startProcess(launch).catch((ex: unknown) => {
+      if (!cancelled) {
+        setDone(true);
+        setFailed(true);
+        setErrorMsg(ex instanceof Error ? ex.message : String(ex));
+      }
+    });
+
+    return () => {
+      cancelled = true;
+      procRef.current?.close();
+    };
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, deps);
+
+  const cancel = useCallback(() => {
+    procRef.current?.close();
+    procRef.current = null;
+  }, []);
+
+  return { lines, done, failed, errorMsg, cancel };
+}

package/src/hooks/useAutoRefresh.test.ts

@@ -0,0 +1,106 @@
+import { renderHook, act } from "@testing-library/react";
+import { vi, describe, it, expect, beforeEach, afterEach } from "vitest";
+import { useAutoRefresh } from "./useAutoRefresh";
+
+describe("useAutoRefresh", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    Object.defineProperty(document, "hidden", { value: false, configurable: true, writable: true });
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("calls fn at the given interval", () => {
+    const fn = vi.fn();
+    renderHook(() => useAutoRefresh(fn, 1000));
+
+    expect(fn).not.toHaveBeenCalled();
+    act(() => { vi.advanceTimersByTime(1000); });
+    expect(fn).toHaveBeenCalledTimes(1);
+    act(() => { vi.advanceTimersByTime(2000); });
+    expect(fn).toHaveBeenCalledTimes(3);
+  });
+
+  it("does not call fn when paused", () => {
+    const fn = vi.fn();
+    renderHook(() => useAutoRefresh(fn, 1000, true));
+
+    act(() => { vi.advanceTimersByTime(3000); });
+    expect(fn).not.toHaveBeenCalled();
+  });
+
+  it("does not call fn when tab is hidden", () => {
+    const fn = vi.fn();
+    Object.defineProperty(document, "hidden", { value: true, configurable: true, writable: true });
+    renderHook(() => useAutoRefresh(fn, 1000));
+
+    act(() => { vi.advanceTimersByTime(3000); });
+    expect(fn).not.toHaveBeenCalled();
+  });
+
+  it("resumes polling when tab becomes visible", () => {
+    const fn = vi.fn();
+    Object.defineProperty(document, "hidden", { value: true, configurable: true, writable: true });
+    renderHook(() => useAutoRefresh(fn, 1000));
+
+    act(() => { vi.advanceTimersByTime(2000); });
+    expect(fn).not.toHaveBeenCalled();
+
+    act(() => {
+      Object.defineProperty(document, "hidden", { value: false, configurable: true, writable: true });
+      document.dispatchEvent(new Event("visibilitychange"));
+    });
+
+    act(() => { vi.advanceTimersByTime(1000); });
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it("pauses polling when tab becomes hidden", () => {
+    const fn = vi.fn();
+    renderHook(() => useAutoRefresh(fn, 1000));
+
+    act(() => { vi.advanceTimersByTime(1000); });
+    expect(fn).toHaveBeenCalledTimes(1);
+
+    act(() => {
+      Object.defineProperty(document, "hidden", { value: true, configurable: true, writable: true });
+      document.dispatchEvent(new Event("visibilitychange"));
+    });
+
+    act(() => { vi.advanceTimersByTime(3000); });
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it("clears the interval on unmount", () => {
+    const fn = vi.fn();
+    const { unmount } = renderHook(() => useAutoRefresh(fn, 1000));
+
+    act(() => { vi.advanceTimersByTime(1000); });
+    expect(fn).toHaveBeenCalledTimes(1);
+
+    unmount();
+    act(() => { vi.advanceTimersByTime(5000); });
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it("picks up the latest fn ref without restarting the interval", () => {
+    let callCount = 0;
+    const fn1 = vi.fn(() => { callCount++; });
+    const fn2 = vi.fn(() => { callCount += 10; });
+
+    const { rerender } = renderHook(({ f }) => useAutoRefresh(f, 1000), {
+      initialProps: { f: fn1 },
+    });
+
+    act(() => { vi.advanceTimersByTime(1000); });
+    expect(callCount).toBe(1);
+
+    rerender({ f: fn2 });
+    act(() => { vi.advanceTimersByTime(1000); });
+    expect(callCount).toBe(11);
+    expect(fn1).toHaveBeenCalledTimes(1);
+    expect(fn2).toHaveBeenCalledTimes(1);
+  });
+});

package/src/hooks/useAutoRefresh.ts

@@ -0,0 +1,23 @@
+import { useEffect, useRef, useState } from "react";
+
+export function useAutoRefresh(
+  fn: () => void | Promise<void>,
+  intervalMs: number,
+  paused = false,
+): void {
+  const fnRef = useRef(fn);
+  useEffect(() => { fnRef.current = fn; }, [fn]);
+
+  const [tabHidden, setTabHidden] = useState(() => document.hidden);
+  useEffect(() => {
+    const handler = () => setTabHidden(document.hidden);
+    document.addEventListener("visibilitychange", handler);
+    return () => document.removeEventListener("visibilitychange", handler);
+  }, []);
+
+  useEffect(() => {
+    if (paused || tabHidden) return;
+    const t = setInterval(() => void fnRef.current(), intervalMs);
+    return () => clearInterval(t);
+  }, [paused, tabHidden, intervalMs]);
+}

package/src/hooks/useConfirmAction.test.ts

@@ -0,0 +1,68 @@
+import { renderHook, act } from "@testing-library/react";
+import { describe, it, expect, vi } from "vitest";
+import { useConfirmAction } from "./useConfirmAction";
+
+describe("useConfirmAction", () => {
+  it("starts idle with no error", () => {
+    const { result } = renderHook(() => useConfirmAction());
+    expect(result.current.step).toBe("idle");
+    expect(result.current.error).toBeNull();
+  });
+
+  it("confirm() moves to confirming", () => {
+    const { result } = renderHook(() => useConfirmAction());
+    act(() => { result.current.confirm(); });
+    expect(result.current.step).toBe("confirming");
+  });
+
+  it("cancel() resets to idle and clears error", async () => {
+    const { result } = renderHook(() => useConfirmAction());
+    act(() => { result.current.confirm(); });
+
+    await act(async () => {
+      await result.current.submit(vi.fn().mockRejectedValue(new Error("fail")));
+    });
+    expect(result.current.error).toBe("fail");
+
+    act(() => { result.current.cancel(); });
+    expect(result.current.step).toBe("idle");
+    expect(result.current.error).toBeNull();
+  });
+
+  it("submit() transitions: confirming → submitting → idle on success", async () => {
+    const action = vi.fn().mockResolvedValue(undefined);
+    const { result } = renderHook(() => useConfirmAction());
+
+    act(() => { result.current.confirm(); });
+    expect(result.current.step).toBe("confirming");
+
+    await act(async () => { await result.current.submit(action); });
+    expect(result.current.step).toBe("idle");
+    expect(result.current.error).toBeNull();
+    expect(action).toHaveBeenCalledTimes(1);
+  });
+
+  it("submit() transitions: submitting → confirming on failure, with error set", async () => {
+    const action = vi.fn().mockRejectedValue(new Error("server error"));
+    const { result } = renderHook(() => useConfirmAction());
+
+    act(() => { result.current.confirm(); });
+
+    await act(async () => { await result.current.submit(action); });
+    expect(result.current.step).toBe("confirming");
+    expect(result.current.error).toBe("server error");
+  });
+
+  it("clearError() clears error without changing step", async () => {
+    const action = vi.fn().mockRejectedValue(new Error("oops"));
+    const { result } = renderHook(() => useConfirmAction());
+
+    act(() => { result.current.confirm(); });
+    await act(async () => { await result.current.submit(action); });
+    expect(result.current.error).toBe("oops");
+
+    act(() => { result.current.clearError(); });
+    expect(result.current.error).toBeNull();
+    expect(result.current.step).toBe("confirming");
+  });
+});

package/src/hooks/useConfirmAction.ts

@@ -0,0 +1,35 @@
+import { useState, useCallback } from "react";
+
+export type ConfirmStep = "idle" | "confirming" | "submitting";
+
+export interface ConfirmActionState {
+  step: ConfirmStep;
+  error: string | null;
+  confirm: () => void;
+  cancel: () => void;
+  submit: (action: () => Promise<void>) => Promise<void>;
+  clearError: () => void;
+}
+
+export function useConfirmAction(): ConfirmActionState {
+  const [step, setStep] = useState<ConfirmStep>("idle");
+  const [error, setError] = useState<string | null>(null);
+
+  const confirm = useCallback(() => setStep("confirming"), []);
+  const cancel = useCallback(() => { setStep("idle"); setError(null); }, []);
+  const clearError = useCallback(() => setError(null), []);
+
+  const submit = useCallback(async (action: () => Promise<void>) => {
+    setStep("submitting");
+    setError(null);
+    try {
+      await action();
+      setStep("idle");
+    } catch (e) {
+      setError(e instanceof Error ? e.message : String(e));
+      setStep("confirming");
+    }
+  }, []);
+
+  return { step, error, confirm, cancel, submit, clearError };
+}

package/src/hooks/usePollingFetch.ts

@@ -0,0 +1,41 @@
+import { useState, useCallback, useEffect } from "react";
+import { useAutoRefresh } from "./useAutoRefresh";
+
+export interface PollingFetchResult<T> {
+  data: T;
+  loading: boolean;
+  error: string | null;
+  refresh: () => Promise<void>;
+}
+
+/**
+ * Initial fetch shows loading=true; subsequent background polls update silently.
+ * Calling refresh() manually also runs silently (no loading flash).
+ */
+export function usePollingFetch<T>(
+  fetcher: () => Promise<T>,
+  initial: T,
+  intervalMs: number,
+  paused = false,
+): PollingFetchResult<T> {
+  const [data, setData] = useState<T>(initial);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  const refresh = useCallback(async () => {
+    try {
+      const result = await fetcher();
+      setData(result);
+      setError(null);
+    } catch (e) {
+      setError(e instanceof Error ? e.message : String(e));
+    } finally {
+      setLoading(false);
+    }
+  }, [fetcher]);
+
+  useEffect(() => { void refresh(); }, [refresh]);
+  useAutoRefresh(refresh, intervalMs, paused);
+
+  return { data, loading, error, refresh };
+}

package/src/i18n.ts

@@ -0,0 +1,51 @@
+import i18n from "i18next";
+import { initReactI18next } from "react-i18next";
+
+export type LocaleResources = Record<string, { translation: Record<string, unknown> }>;
+
+// Reads Cockpit's language setting in priority order:
+// 1. document.documentElement.lang — Cockpit sets this live when the user changes language
+// 2. localStorage["cockpit:language"] — Cockpit mirrors the preference here
+// 3. Falls back to "en" via fallbackLng
+const cockpitDetector = {
+  name: "cockpit",
+  detect(): string | undefined {
+    const htmlLang = document.documentElement.lang;
+    if (htmlLang) return htmlLang;
+    try {
+      const stored = localStorage.getItem("cockpit:language");
+      if (stored) return stored;
+    } catch {
+      // localStorage may be unavailable in restricted contexts
+    }
+    return undefined;
+  },
+  cacheUserLanguage() {
+    // Language is owned by Cockpit settings — never write back
+  },
+};
+
+export function initCockpitI18n(resources: LocaleResources): void {
+  void i18n
+    .use({ type: "languageDetector", ...cockpitDetector } as Parameters<typeof i18n.use>[0])
+    .use(initReactI18next)
+    .init({
+      resources,
+      fallbackLng: "en",
+      load: "all",
+      interpolation: {
+        escapeValue: false,
+      },
+    });
+
+  // Cockpit updates document.documentElement.lang when the user switches language at runtime.
+  // i18next only detects on init, so we observe the attribute and sync the change.
+  new MutationObserver(() => {
+    const lang = document.documentElement.lang;
+    if (lang && lang !== i18n.language) {
+      void i18n.changeLanguage(lang);
+    }
+  }).observe(document.documentElement, { attributeFilter: ["lang"] });
+}
+
+export { i18n };

package/src/index.ts

@@ -0,0 +1,11 @@
+export { initCockpitI18n } from "./i18n";
+export type { LocaleResources } from "./i18n";
+export { bootstrapPlugin } from "./bootstrap";
+export { useAsyncAction } from "./hooks/useAsyncAction";
+export { useAutoRefresh } from "./hooks/useAutoRefresh";
+export { useAsyncStream } from "./hooks/useAsyncStream";
+export type { AsyncStreamResult } from "./hooks/useAsyncStream";
+export { useConfirmAction } from "./hooks/useConfirmAction";
+export type { ConfirmStep, ConfirmActionState } from "./hooks/useConfirmAction";
+export { usePollingFetch } from "./hooks/usePollingFetch";
+export type { PollingFetchResult } from "./hooks/usePollingFetch";