docs: create-and-check-documentation

src/components/Logging/Logging.tsx

@@ -8,13 +8,26 @@ import {type Cell, useCell} from "../../utils/cellStore.ts";
 
 import styles from "./Logging.module.css";
 
+
+/**
+ * Zustand store definition for managing user preferences related to logging.
+ *
+ * Includes flags for toggling relative timestamps and automatic scroll behavior.
+ */
 type LoggingSettings = {
+  /** Whether to display log timestamps as relative (e.g., "2m 15s ago") instead of absolute. */
   showRelativeTime: boolean;
+  /** Updates the `showRelativeTime` setting. */
   setShowRelativeTime: (showRelativeTime: boolean) => void;
+  /** Whether the log view should automatically scroll to the newest entry. */
   scrollToBottom: boolean;
+  /** Updates the `scrollToBottom` setting. */
   setScrollToBottom: (scrollToBottom: boolean) => void;
 };
 
+/**
+ * Global Zustand store for logging UI preferences.
+ */
 const useLoggingSettings = create<LoggingSettings>((set) => ({
   showRelativeTime: false,
   setShowRelativeTime: (showRelativeTime: boolean) => set({ showRelativeTime }),
@@ -22,6 +35,16 @@ const useLoggingSettings = create<LoggingSettings>((set) => ({
   setScrollToBottom: (scrollToBottom: boolean) => set({ scrollToBottom }),
 }));
 
+/**
+ * Renders a single log message entry with colored level indicators and timestamp formatting.
+ *
+ * This component automatically re-renders when the underlying log record (`recordCell`)
+ * changes. It also triggers the `onUpdate` callback whenever the record updates (e.g., for auto-scrolling).
+ *
+ * @param recordCell - A reactive `Cell` containing a single `LogRecord`.
+ * @param onUpdate - Optional callback triggered when the log entry updates.
+ * @returns A JSX element displaying a formatted log message.
+ */
 function LogMessage({
   recordCell,
   onUpdate,
@@ -33,7 +56,8 @@ function LogMessage({
   const record = useCell(recordCell);
 
   /**
-   * Normalizes the log level number to a multiple of 10, for which there are CSS styles.
+   * Normalizes the log level number to a multiple of 10, 
+   * for which there are CSS styles. (e.g., INFO = 20, ERROR = 40).
    */
   const normalizedLevelNo = (() => {
     // By default, the highest level is 50 (CRITICAL). Custom levels can be higher, but we don't have more critical color.
@@ -42,8 +66,10 @@ function LogMessage({
     return Math.round(record.levelno / 10) * 10;
   })();
 
+  /** Simplifies the logger name by showing only the last path segment. */
   const normalizedName = record.name.split(".").pop() || record.name;
 
+  // Notify parent component (e.g. for scroll updates) when this record changes.
   useEffect(() => {
     if (onUpdate) onUpdate();
   }, [record, onUpdate]);
@@ -65,11 +91,23 @@ function LogMessage({
   </div>;
 }
 
+/**
+ * Displays a scrollable list of log messages.
+ *
+ * Handles:
+ * - Auto-scrolling when new messages arrive.
+ * - Allowing users to scroll manually and disable auto-scroll.
+ * - A floating "Scroll to bottom" button when not at the bottom.
+ *
+ * @param recordCells - Array of reactive log records to display.
+ * @returns A scrollable log list component.
+ */
 function LogMessages({ recordCells }: { recordCells: Cell<LogRecord>[] }) {
   const scrollableRef = useRef<HTMLDivElement>(null);
   const lastElementRef = useRef<HTMLLIElement>(null)
   const { scrollToBottom, setScrollToBottom } = useLoggingSettings();
 
+  // Disable auto-scroll if the user manually scrolls.
   useEffect(() => {
     if (!scrollableRef.current) return;
     const currentScrollableRef = scrollableRef.current;
@@ -85,6 +123,12 @@ function LogMessages({ recordCells }: { recordCells: Cell<LogRecord>[] }) {
     }
   }, [scrollableRef, setScrollToBottom]);
 
+  /**
+   * Scrolls the last log message into view if auto-scroll is enabled,
+   * or if forced (e.g., user clicks "Scroll to bottom").
+   *
+   * @param force - If true, forces scrolling even if `scrollToBottom` is false.
+   */
   function scrollLastElementIntoView(force = false) {
     if ((!scrollToBottom && !force) || !lastElementRef.current) return;
     lastElementRef.current.scrollIntoView({ behavior: "smooth" });
@@ -111,6 +155,19 @@ function LogMessages({ recordCells }: { recordCells: Cell<LogRecord>[] }) {
   </div>;
 }
 
+/**
+ * Top-level logging panel component.
+ *
+ * Combines:
+ * - The `Filters` component for adjusting log visibility.
+ * - The `LogMessages` component for displaying filtered logs.
+ * - Zustand-managed UI settings (auto-scroll, timestamp display).
+ *
+ * This component uses the `useLogs` hook to fetch and filter logs based on
+ * active predicates, and re-renders automatically as new logs arrive.
+ *
+ * @returns The complete logging UI as a React element.
+ */
 export default function Logging() {
   const [filterPredicates, setFilterPredicates] = useState(new Map<string, LogFilterPredicate>());
   const { filteredLogs, distinctNames } = useLogs(filterPredicates)