@rxtx4816/cockpit-plugin-base-react 1.0.3 → 1.0.5

package/README.md

@@ -73,6 +73,8 @@ For full setup guidance, config sharing, and workflow integration see the [wiki]
 
 ## Documentation
 
+**[API Reference](https://rxtx4816.github.io/cockpit-plugin-base-react/)** — auto-generated from source, updated on every release.
+
 - [Getting Started](docs/wiki/Getting-Started.md)
 - [Hooks](docs/wiki/Hooks.md)
 - [Components](docs/wiki/Components.md)

package/docs/wiki/Home.md

@@ -2,6 +2,8 @@
 
 This wiki covers everything you need to build, test, and ship Cockpit plugins using `@rxtx4816/cockpit-plugin-base-react`.
 
+**[API Reference](https://rxtx4816.github.io/cockpit-plugin-base-react/)** — auto-generated TypeDoc, updated on every release.
+
 ## Contents
 
 - [Getting Started](Getting-Started.md) — install, bootstrap, and first plugin setup

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rxtx4816/cockpit-plugin-base-react",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "Shared infrastructure for Cockpit plugins: i18n, dark theme, test setup, config presets, CI/CD workflows, and QEMU VM harness",
   "type": "module",
   "author": "RXTX4816",
@@ -80,7 +80,9 @@
     "lint": "eslint src/",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
-    "test:watch": "vitest"
+    "test:watch": "vitest",
+    "docs": "typedoc",
+    "docs:watch": "typedoc --watch"
   },
   "peerDependencies": {
     "i18next": ">=26",
@@ -104,6 +106,7 @@
     "react": "^19.2.7",
     "react-dom": "^19.2.7",
     "react-i18next": "^17.0.8",
+    "typedoc": "^0.28.19",
     "typescript": "^6.0.3",
     "vitest": "^4.1.9"
   },

package/src/bootstrap.tsx

@@ -1,6 +1,13 @@
 import { ComponentType } from "react";
 import { createRoot } from "react-dom/client";
 
+/**
+ * Mounts a React application into the `#root` DOM element.
+ *
+ * Call this once at the plugin entry point after {@link initCockpitI18n}.
+ *
+ * @param App - The root React component to render.
+ */
 export function bootstrapPlugin(App: ComponentType): void {
   const root = createRoot(document.getElementById("root")!);
   root.render(<App />);

package/src/cockpit.d.ts

@@ -39,8 +39,16 @@ declare interface CockpitUser {
   groups: string[];
 }
 
+declare interface CockpitPermission {
+  allowed: boolean | null;
+  addEventListener(event: "changed", callback: () => void): void;
+  removeEventListener(event: "changed", callback: () => void): void;
+  close(): void;
+}
+
 declare const cockpit: {
   user(): Promise<CockpitUser>;
+  permission(options: { admin: boolean }): CockpitPermission;
   spawn(
     args: string[],
     options?: { superuser?: "try" | "require"; err?: string; environ?: string[] }

package/src/components/ConfirmDialog.tsx

@@ -9,18 +9,33 @@ import {
 import type { ReactNode } from "react";
 
 interface Props {
+  /** Controls modal visibility. */
   isOpen: boolean;
+  /** Modal heading text. */
   title: string;
+  /** Optional body content rendered above the inline error alert. */
   body?: ReactNode;
+  /** Label for the primary confirm button. */
   confirmLabel: string;
+  /** Label for the cancel button. Defaults to `"Cancel"`. */
   cancelLabel?: string;
+  /** Button variant — use `"danger"` for destructive actions. Defaults to `"primary"`. */
   variant?: "primary" | "danger";
+  /** When `true`, the confirm button shows a spinner and both buttons are disabled. */
   loading?: boolean;
+  /** If set, renders an inline danger alert above the footer buttons. */
   error?: string | null;
+  /** Called when the user clicks the confirm button. */
   onConfirm: () => void;
+  /** Called when the user clicks cancel or closes the modal. */
   onClose: () => void;
 }
 
+/**
+ * A PatternFly `Modal` wired up for a single confirm/cancel action.
+ *
+ * Pair with `useConfirmAction` to manage the open/close and loading state.
+ */
 export function ConfirmDialog({
   isOpen,
   title,

package/src/components/ErrorBoundary.tsx

@@ -3,6 +3,7 @@ import { EmptyState, EmptyStateBody } from "@patternfly/react-core";
 
 interface Props {
   children: ReactNode;
+  /** Heading shown in the PatternFly EmptyState fallback. Defaults to `"Something went wrong"`. */
   fallbackTitle?: string;
 }
 
@@ -10,6 +11,10 @@ interface State {
   error: Error | null;
 }
 
+/**
+ * React error boundary that catches unhandled render errors and displays a
+ * PatternFly `EmptyState` fallback instead of a blank page.
+ */
 export class ErrorBoundary extends Component<Props, State> {
   state: State = { error: null };
 

package/src/components/HelpPopover.tsx

@@ -3,11 +3,17 @@ import { Popover, Button } from "@patternfly/react-core";
 import { OutlinedQuestionCircleIcon } from "@patternfly/react-icons";
 
 interface Props {
+  /** Popover heading text. */
   header: string;
+  /** Popover body text. */
   body: string;
+  /** `aria-label` for the trigger button. Defaults to `header`. */
   "aria-label"?: string;
 }
 
+/**
+ * A question-mark icon button that opens a PatternFly `Popover` with help text.
+ */
 export function HelpPopover({ header, body, "aria-label": ariaLabel }: Props) {
   const [visible, setVisible] = useState(false);
   return (

package/src/components/LogViewer.tsx

@@ -12,17 +12,32 @@ import {
 } from "@patternfly/react-core";
 
 interface Props {
+  /** Log lines to display. Each string becomes one line in the pre block. */
   lines: string[];
+  /** When `true`, shows a spinner instead of the log content. */
   loading?: boolean;
+  /** If set, renders a danger alert at the top of the component. */
   error?: string | null;
+  /** When provided, adds a refresh button to the toolbar. */
   onRefresh?: () => void;
+  /** Placeholder text for the search input. Defaults to `"Search logs…"`. */
   searchPlaceholder?: string;
+  /** Message shown when `lines` is empty. Defaults to `"No log entries."`. */
   emptyMessage?: string;
+  /** Message shown when the search filter matches nothing. Defaults to `"No matching entries."`. */
   noMatchesMessage?: string;
+  /** Title of the danger alert when `error` is set. Defaults to `"Failed to load logs"`. */
   errorTitle?: string;
+  /** `aria-label` for the refresh button. Defaults to `"Refresh"`. */
   refreshAriaLabel?: string;
 }
 
+/**
+ * A scrollable, searchable log viewer with a toolbar.
+ *
+ * Pass `lines` from `useAsyncStream` or any string array. The search
+ * input filters lines client-side; `onRefresh` adds a refresh button.
+ */
 export function LogViewer({
   lines,
   loading = false,

package/src/components/StatusBadge.tsx

@@ -1,17 +1,38 @@
 import { Label, type LabelProps } from "@patternfly/react-core";
 
+/**
+ * Display configuration for a single status value.
+ */
 export interface StatusBadgeConfig {
+  /** PatternFly label color. */
   color: LabelProps["color"];
+  /** Human-readable label text. */
   label: string;
 }
 
 interface Props<T extends string> {
+  /** The current status value to look up in `config`. */
   status: T;
+  /** Map of status values to their display configuration. */
   config: Record<string, StatusBadgeConfig>;
+  /** Shown when `status` has no entry in `config`. Defaults to a grey label with the raw status string. */
   fallback?: StatusBadgeConfig;
+  /** Renders a compact PatternFly `Label`. */
   isCompact?: boolean;
 }
 
+/**
+ * Renders a PatternFly `Label` whose color and text are driven by a `config` map.
+ *
+ * @example
+ * ```tsx
+ * const STATUS_CONFIG: Record<ServiceStatus, StatusBadgeConfig> = {
+ *   active:  { color: "green", label: "Active" },
+ *   failed:  { color: "red",   label: "Failed" },
+ * };
+ * <StatusBadge status={serviceStatus} config={STATUS_CONFIG} />
+ * ```
+ */
 export function StatusBadge<T extends string>({ status, config, fallback, isCompact }: Props<T>) {
   const entry = config[status] ?? fallback ?? { color: "grey", label: status };
   return <Label color={entry.color} isCompact={isCompact}>{entry.label}</Label>;

package/src/components/ToastProvider.tsx

@@ -2,6 +2,7 @@ import { createContext, useCallback, useContext, useRef, useState, type ReactNod
 import { Alert, AlertGroup, AlertActionCloseButton } from "@patternfly/react-core";
 import "./ToastProvider.css";
 
+/** Severity level of a toast notification. */
 export type ToastVariant = "success" | "danger" | "warning" | "info";
 
 interface Toast {
@@ -11,11 +12,19 @@ interface Toast {
   body?: string;
 }
 
+/**
+ * Context value exposed by {@link ToastProvider} and consumed by {@link useToast}.
+ */
 export interface ToastContextValue {
+  /** Adds a toast with an explicit variant. */
   addToast: (variant: ToastVariant, title: string, body?: string) => void;
+  /** Shorthand for `addToast("success", ...)`. */
   success: (title: string, body?: string) => void;
+  /** Shorthand for `addToast("danger", ...)`. */
   error: (title: string, body?: string) => void;
+  /** Shorthand for `addToast("warning", ...)`. */
   warn: (title: string, body?: string) => void;
+  /** Shorthand for `addToast("info", ...)`. */
   info: (title: string, body?: string) => void;
 }
 
@@ -23,6 +32,12 @@ const ToastContext = createContext<ToastContextValue | null>(null);
 
 const AUTO_DISMISS_MS = 5000;
 
+/**
+ * Provides toast notification state to the component tree.
+ *
+ * Wrap your app root with `<ToastProvider>` and call {@link useToast} anywhere
+ * inside to fire notifications. Toasts auto-dismiss after 5 seconds.
+ */
 export function ToastProvider({ children }: { children: ReactNode }) {
   const [toasts, setToasts] = useState<Toast[]>([]);
   const counterRef = useRef(0);
@@ -71,6 +86,12 @@ const NOOP_TOAST: ToastContextValue = {
   info: () => {},
 };
 
+/**
+ * Returns the nearest {@link ToastProvider}'s context value.
+ *
+ * Falls back to a no-op implementation when called outside a `ToastProvider`,
+ * so it is safe to use in unit tests without a provider wrapper.
+ */
 export function useToast(): ToastContextValue {
   return useContext(ToastContext) ?? NOOP_TOAST;
 }

package/src/hooks/useAsyncAction.ts

@@ -1,5 +1,13 @@
 import { useState, useCallback } from "react";
 
+/**
+ * Wraps an async function with `loading` and `error` state.
+ *
+ * @param action - The async function to execute. A new stable reference should be
+ *   passed via `useCallback` to avoid unnecessary re-renders.
+ * @returns An object with `execute` (calls the action), `loading`, `error`, and
+ *   `clearError` (resets the error state).
+ */
 export function useAsyncAction<T>(
   action: () => Promise<T>,
 ): {

package/src/hooks/useAsyncStream.ts

@@ -1,23 +1,34 @@
 import { useState, useEffect, useRef, useCallback } from "react";
 
+/**
+ * Accumulated result of a streaming Cockpit process.
+ */
 export interface AsyncStreamResult {
+  /** All output lines received so far, with blank lines and CR stripped. */
   lines: string[];
+  /** `true` once the process exits (success or failure). */
   done: boolean;
+  /** `true` when the process exited with an error. */
   failed: boolean;
+  /** Error message when `failed` is `true`, otherwise empty string. */
   errorMsg: string;
+  /** Closes the underlying process and stops accumulating output. */
   cancel: () => void;
 }
 
 /**
- * Generic hook for accumulating line-buffered output from a CockpitProcess.
+ * Accumulates line-buffered output from a Cockpit process into a `lines` array.
  *
  * 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().
+ * 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 `deps` array works like `useEffect` deps — the hook tears down and restarts
  * the process whenever any dep changes.
+ *
+ * @param startProcess - Factory that receives a `launch` callback and must call it with the process.
+ * @param deps - Re-run dependencies (same semantics as `useEffect`).
  */
 export function useAsyncStream(
   startProcess: (launch: (proc: CockpitProcess) => void) => Promise<void>,

package/src/hooks/useAutoRefresh.ts

@@ -1,5 +1,12 @@
 import { useEffect, useRef, useState } from "react";
 
+/**
+ * Calls `fn` on a repeating interval, pausing automatically when the browser tab is hidden.
+ *
+ * @param fn - The callback to invoke on each tick. May be async — rejections are swallowed.
+ * @param intervalMs - Interval duration in milliseconds.
+ * @param paused - When `true`, suspends polling without tearing down the effect.
+ */
 export function useAutoRefresh(
   fn: () => void | Promise<void>,
   intervalMs: number,

package/src/hooks/useConfirmAction.ts

@@ -1,16 +1,34 @@
 import { useState, useCallback } from "react";
 
+/** Current phase of the confirmation flow. */
 export type ConfirmStep = "idle" | "confirming" | "submitting";
 
+/**
+ * State and controls returned by {@link useConfirmAction}.
+ */
 export interface ConfirmActionState {
+  /** Current phase of the flow. */
   step: ConfirmStep;
+  /** Error message from the last failed `submit`, or `null`. */
   error: string | null;
+  /** Transitions from `idle` → `confirming`, opening the dialog. */
   confirm: () => void;
+  /** Transitions back to `idle` and clears the error. */
   cancel: () => void;
+  /**
+   * Runs `action` while in the `submitting` phase.
+   * On success transitions to `idle`; on failure stays in `confirming` with `error` set.
+   */
   submit: (action: () => Promise<void>) => Promise<void>;
+  /** Clears the error without changing the step. */
   clearError: () => void;
 }
 
+/**
+ * Manages state for a multi-step confirmation flow: idle → confirming → submitting.
+ *
+ * Pair with `ConfirmDialog` to wire up the confirmation modal.
+ */
 export function useConfirmAction(): ConfirmActionState {
   const [step, setStep] = useState<ConfirmStep>("idle");
   const [error, setError] = useState<string | null>(null);

package/src/hooks/usePollingFetch.ts

@@ -1,16 +1,31 @@
 import { useState, useCallback, useEffect } from "react";
 import { useAutoRefresh } from "./useAutoRefresh";
 
+/**
+ * Result returned by {@link usePollingFetch}.
+ */
 export interface PollingFetchResult<T> {
+  /** Most recently fetched value, or `initial` before the first fetch completes. */
   data: T;
+  /** `true` only during the initial fetch — background polls update silently. */
   loading: boolean;
+  /** Error message from the most recent failed fetch, or `null`. */
   error: string | null;
+  /** Manually triggers a fetch; runs silently (no `loading` flash). */
   refresh: () => Promise<void>;
 }
 
 /**
- * Initial fetch shows loading=true; subsequent background polls update silently.
- * Calling refresh() manually also runs silently (no loading flash).
+ * Fetches data on mount and then polls at a fixed interval.
+ *
+ * The initial load sets `loading = true`; subsequent background polls and manual
+ * `refresh()` calls update `data` silently without a loading flash.
+ *
+ * @param fetcher - Async function that returns the data. Wrap in `useCallback` to
+ *   avoid restarting the interval on every render.
+ * @param initial - Value used for `data` before the first fetch resolves.
+ * @param intervalMs - Polling interval in milliseconds.
+ * @param paused - When `true`, pauses background polling (does not cancel an in-flight request).
  */
 export function usePollingFetch<T>(
   fetcher: () => Promise<T>,

package/src/i18n.ts

@@ -1,6 +1,10 @@
 import i18n from "i18next";
 import { initReactI18next } from "react-i18next";
 
+/**
+ * i18next `resources` map keyed by locale (e.g. `"en"`, `"de"`), each with a
+ * `translation` namespace object. Pass this to {@link initCockpitI18n}.
+ */
 export type LocaleResources = Record<string, { translation: Record<string, unknown> }>;
 
 // Reads Cockpit's language setting in priority order:
@@ -25,6 +29,14 @@ const cockpitDetector = {
   },
 };
 
+/**
+ * Initialises i18next with Cockpit's active locale and sets up a live observer
+ * so the UI re-translates when the user switches language in Cockpit settings.
+ *
+ * Call once at plugin startup, before {@link bootstrapPlugin}.
+ *
+ * @param resources - Translation resources keyed by locale. See {@link LocaleResources}.
+ */
 export function initCockpitI18n(resources: LocaleResources): void {
   void i18n
     .use({ type: "languageDetector", ...cockpitDetector } as Parameters<typeof i18n.use>[0])

package/src/systemd/ServiceControl.tsx

@@ -7,12 +7,22 @@ import type { ServiceStatus } from "./types";
 
 type PendingAction = "start" | "stop" | "restart" | "reload";
 
+/**
+ * Overrides for all user-visible strings in {@link ServiceControl}.
+ * Every field is optional — unset fields fall back to English defaults.
+ */
 export interface ServiceControlLabels {
+  /** Start button label. */
   start?: string;
+  /** Stop button label. */
   stop?: string;
+  /** Restart button label. */
   restart?: string;
+  /** Reload button label. */
   reload?: string;
+  /** Cancel button label in the confirmation dialog. */
   cancel?: string;
+  /** Confirm button label in the confirmation dialog. */
   confirmAction?: string;
   confirmStartTitle?: string;
   confirmStartBody?: string;
@@ -22,6 +32,10 @@ export interface ServiceControlLabels {
   confirmRestartBody?: string;
   confirmReloadTitle?: string;
   confirmReloadBody?: string;
+  successStart?: string;
+  successStop?: string;
+  successRestart?: string;
+  successReload?: string;
 }
 
 const DEFAULTS: Required<ServiceControlLabels> = {
@@ -39,17 +53,35 @@ const DEFAULTS: Required<ServiceControlLabels> = {
   confirmRestartBody: "The service will be restarted.",
   confirmReloadTitle: "Reload service?",
   confirmReloadBody: "The service configuration will be reloaded.",
+  successStart: "Service started",
+  successStop: "Service stopped",
+  successRestart: "Service restarted",
+  successReload: "Configuration reloaded",
 };
 
 interface Props {
+  /** The systemd unit name (e.g. `"nginx.service"`). */
   unit: string;
+  /** Current unit status — drives which buttons are enabled. */
   status: ServiceStatus;
+  /** When `true`, shows a spinner in place of the status badge. */
   loading?: boolean;
+  /** Called after a successful action so the parent can re-poll status. */
   onRefresh?: () => void;
+  /** Optional status badge rendered to the left of the action buttons. */
   statusBadge?: ReactNode;
+  /** Override any user-visible string. See {@link ServiceControlLabels}. */
   labels?: ServiceControlLabels;
 }
 
+/**
+ * A row of Start / Stop / Restart / Reload buttons for a systemd unit.
+ *
+ * Each action opens a `ConfirmDialog` before executing. Errors are shown
+ * both inline in the dialog and via the nearest `ToastProvider`.
+ *
+ * Pair with `useServiceStatus` for reactive status updates.
+ */
 export function ServiceControl({ unit, status, loading = false, onRefresh, statusBadge, labels }: Props) {
   const toast = useToast();
   const l = { ...DEFAULTS, ...labels };
@@ -64,12 +96,20 @@ export function ServiceControl({ unit, status, loading = false, onRefresh, statu
     reload: () => reloadService(unit),
   };
 
+  const successLabel: Record<PendingAction, string> = {
+    start: l.successStart,
+    stop: l.successStop,
+    restart: l.successRestart,
+    reload: l.successReload,
+  };
+
   async function runAction() {
     if (!pendingAction) return;
     setBusy(true);
     setActionError(null);
     try {
       await ACTION_FN[pendingAction]();
+      toast.success(successLabel[pendingAction]);
       setPendingAction(null);
       onRefresh?.();
     } catch (e) {
@@ -88,6 +128,7 @@ export function ServiceControl({ unit, status, loading = false, onRefresh, statu
 
   const isRunning = status === "active";
   const notInstalled = status === "not-installed";
+  const isDisabledBase = busy || loading || notInstalled;
 
   const confirmTitle: Record<PendingAction, string> = {
     start: l.confirmStartTitle,
@@ -117,7 +158,7 @@ export function ServiceControl({ unit, status, loading = false, onRefresh, statu
           <Button
             variant="primary"
             size="sm"
-            isDisabled={busy || notInstalled || isRunning}
+            isDisabled={isDisabledBase || isRunning}
             onClick={() => openAction("start")}
           >
             {l.start}
@@ -127,7 +168,7 @@ export function ServiceControl({ unit, status, loading = false, onRefresh, statu
           <Button
             variant="secondary"
             size="sm"
-            isDisabled={busy || notInstalled || !isRunning}
+            isDisabled={isDisabledBase || !isRunning}
             onClick={() => openAction("stop")}
           >
             {l.stop}
@@ -137,7 +178,7 @@ export function ServiceControl({ unit, status, loading = false, onRefresh, statu
           <Button
             variant="secondary"
             size="sm"
-            isDisabled={busy || notInstalled || !isRunning}
+            isDisabled={isDisabledBase || !isRunning}
             onClick={() => openAction("restart")}
           >
             {l.restart}
@@ -147,7 +188,7 @@ export function ServiceControl({ unit, status, loading = false, onRefresh, statu
           <Button
             variant="plain"
             size="sm"
-            isDisabled={busy || notInstalled || !isRunning}
+            isDisabled={isDisabledBase || !isRunning}
             onClick={() => openAction("reload")}
           >
             {l.reload}

package/src/systemd/api.ts

@@ -1,5 +1,13 @@
 import type { ServiceStatus } from "./types";
 
+/**
+ * Returns the current {@link ServiceStatus} of a systemd unit.
+ *
+ * Checks with `which` first — returns `"not-installed"` when the unit binary is absent.
+ * Then calls `systemctl is-active` and maps the output to a {@link ServiceStatus} value.
+ *
+ * @param unit - The systemd unit name (e.g. `"nginx.service"`).
+ */
 export async function getServiceStatus(unit: string): Promise<ServiceStatus> {
   try {
     await cockpit.spawn(["which", unit]);
@@ -19,18 +27,35 @@ export async function getServiceStatus(unit: string): Promise<ServiceStatus> {
   }
 }
 
+/**
+ * Starts the given systemd unit via `systemctl start`. Requests superuser escalation.
+ * @param unit - The systemd unit name (e.g. `"nginx.service"`).
+ */
 export async function startService(unit: string): Promise<void> {
   await cockpit.spawn(["systemctl", "start", unit], { superuser: "try" });
 }
 
+/**
+ * Stops the given systemd unit via `systemctl stop`. Requests superuser escalation.
+ * @param unit - The systemd unit name (e.g. `"nginx.service"`).
+ */
 export async function stopService(unit: string): Promise<void> {
   await cockpit.spawn(["systemctl", "stop", unit], { superuser: "try" });
 }
 
+/**
+ * Restarts the given systemd unit via `systemctl restart`. Requests superuser escalation.
+ * @param unit - The systemd unit name (e.g. `"nginx.service"`).
+ */
 export async function restartService(unit: string): Promise<void> {
   await cockpit.spawn(["systemctl", "restart", unit], { superuser: "try" });
 }
 
+/**
+ * Reloads the configuration of the given systemd unit via `systemctl reload`.
+ * Requests superuser escalation.
+ * @param unit - The systemd unit name (e.g. `"nginx.service"`).
+ */
 export async function reloadService(unit: string): Promise<void> {
   await cockpit.spawn(["systemctl", "reload", unit], { superuser: "try" });
 }

package/src/systemd/types.ts

@@ -1 +1,10 @@
+/**
+ * Possible states of a systemd service unit.
+ *
+ * - `"active"` — unit is running
+ * - `"inactive"` — unit is stopped
+ * - `"failed"` — unit exited with an error
+ * - `"unknown"` — `systemctl is-active` returned an unrecognised value
+ * - `"not-installed"` — the unit binary was not found on the system
+ */
 export type ServiceStatus = "active" | "inactive" | "failed" | "unknown" | "not-installed";

package/src/systemd/useServiceStatus.ts

@@ -5,6 +5,13 @@ import type { ServiceStatus } from "./types";
 
 const DEFAULT_INTERVAL = 5000;
 
+/**
+ * Polls the status of a systemd unit and returns reactive state.
+ *
+ * @param unit - The systemd unit name (e.g. `"nginx.service"`).
+ * @param intervalMs - How often to re-poll. Defaults to `5000` ms.
+ * @returns `{ status, loading, error, refresh }` — call `refresh()` to force an immediate re-poll.
+ */
 export function useServiceStatus(unit: string, intervalMs = DEFAULT_INTERVAL) {
   const [status, setStatus] = useState<ServiceStatus>("unknown");
   const [loading, setLoading] = useState(true);

package/src/testing/helpers.ts

@@ -1,5 +1,16 @@
 import { vi } from "vitest";
 
+/**
+ * Creates a fake `CockpitProcess` that emits `data` chunks then resolves (or rejects).
+ *
+ * @param data - One or more output chunks delivered via the `stream` callback.
+ * @param error - When provided, the process rejects with this message instead of resolving.
+ *
+ * @example
+ * ```ts
+ * vi.spyOn(cockpit, "spawn").mockReturnValue(mockProcess("hello\nworld\n"));
+ * ```
+ */
 export function mockProcess(data: string | string[], error?: string): CockpitProcess {
   const chunks = Array.isArray(data) ? data : [data];
   let streamCb: ((data: string) => void) | null = null;
@@ -20,6 +31,11 @@ export function mockProcess(data: string | string[], error?: string): CockpitPro
   }) as CockpitProcess;
 }
 
+/**
+ * Creates a fake `CockpitHttpClient` whose `get` method returns canned responses.
+ *
+ * @param responses - Map of URL paths to response body strings. Unmatched paths return `"{}"`.
+ */
 export function mockHttpClient(responses: Record<string, string> = {}): CockpitHttpClient {
   return {
     get: vi.fn((path: string) => Promise.resolve(responses[path] ?? "{}")),