@datarecce/ui 0.1.30 → 0.1.32

package/recce-source/js/src/lib/hooks/useIdleDetection.tsx

@@ -0,0 +1,185 @@
+import throttle from "lodash/throttle";
+import { useCallback, useEffect, useMemo } from "react";
+import { sendKeepAlive } from "@/lib/api/keepAlive";
+import { useApiConfig } from "./ApiConfigContext";
+import { useIdleTimeoutSafe } from "./IdleTimeoutContext";
+import { useRecceInstanceInfo } from "./useRecceInstanceInfo";
+
+/**
+ * Check if debug logging is enabled via window.RECCE_DEBUG_IDLE
+ * Enable in browser console: window.RECCE_DEBUG_IDLE = true
+ * Disable: delete window.RECCE_DEBUG_IDLE
+ */
+function isDebugEnabled(): boolean {
+  // biome-ignore lint/suspicious/noExplicitAny: window flag for debug logging
+  return typeof window !== "undefined" && !!(window as any).RECCE_DEBUG_IDLE;
+}
+
+/**
+ * Log function that only outputs when debug is enabled
+ */
+function debugLog(message: string, data?: Record<string, unknown>) {
+  if (isDebugEnabled()) {
+    if (data) {
+      console.log(message, data);
+    } else {
+      console.log(message);
+    }
+  }
+}
+
+/**
+ * Configuration for idle detection behavior
+ */
+const IDLE_DETECTION_CONFIG = {
+  /** Events to listen for user activity */
+  ACTIVITY_EVENTS: ["focus", "mousemove", "keydown", "scroll"] as const,
+  /**
+   * Throttle event handler execution to reduce JS overhead (150ms).
+   * Uses lodash.throttle with { leading: true, trailing: true } to ensure
+   * immediate response on first activity (leading) and also capture the final
+   * event in a burst (trailing), which is important for user experience.
+   */
+  EVENT_THROTTLE_MS: 150,
+} as const;
+
+/**
+ * Hook to detect user activity and send keep-alive signals to prevent server idle timeout.
+ *
+ * This hook:
+ * - Listens for user activities (focus, mouse, keyboard, scroll)
+ * - Sends keep-alive requests (throttled at axios layer to minimum 3 seconds)
+ * - Pauses when the tab is inactive (using Page Visibility API)
+ * - Immediately sends a keep-alive when tab becomes active
+ * - Only activates when idle_timeout is configured on the server
+ *
+ * Note: The countdown in IdleTimeoutContext is based on successful keep-alive
+ * API calls, not on user activity. This ensures accurate server state tracking.
+ */
+export function useIdleDetection() {
+  const { data: instanceInfo, isLoading, isError } = useRecceInstanceInfo();
+  const idleTimeoutContext = useIdleTimeoutSafe();
+  const isDisconnected = idleTimeoutContext?.isDisconnected ?? false;
+  const { apiClient } = useApiConfig();
+
+  // Only enable idle detection if idle_timeout is configured and not disconnected
+  const idleTimeout = instanceInfo?.idle_timeout;
+  const isEnabled =
+    idleTimeout !== undefined && idleTimeout > 0 && !isDisconnected;
+
+  // Debug: Log instance info state when debug is enabled
+  debugLog("[Idle Detection] Instance info", {
+    isLoading,
+    isError,
+    hasIdleTimeout: idleTimeout !== undefined,
+    idleTimeout:
+      idleTimeout !== undefined ? `${idleTimeout}s` : "not configured",
+    isDisconnected,
+    isEnabled,
+  });
+
+  /**
+   * Send keep-alive signal to server
+   * Throttling is handled at the axios layer (minimum 3 seconds between API calls)
+   * The successful send will notify IdleTimeoutContext to reset countdown
+   */
+  const sendKeepAliveNow = useCallback(async () => {
+    if (document.hidden) return;
+
+    const sent = await sendKeepAlive(apiClient);
+
+    if (sent) {
+      debugLog("[Idle Detection] Keep-alive sent successfully", {
+        timestamp: new Date().toISOString(),
+      });
+    }
+  }, [apiClient]);
+
+  /**
+   * Handle any user activity event
+   * Attempts to send keep-alive (axios layer handles throttling)
+   */
+  const handleActivity = useCallback(
+    (event: Event) => {
+      if (isEnabled && !document.hidden) {
+        debugLog("[Idle Detection] Activity detected", {
+          event: event.type,
+          tabActive: !document.hidden,
+        });
+
+        // Send keep-alive API call (axios layer handles throttling)
+        void sendKeepAliveNow();
+      }
+    },
+    [isEnabled, sendKeepAliveNow],
+  );
+
+  /**
+   * Handle tab visibility changes
+   * When tab becomes active, attempt to send keep-alive
+   */
+  const handleVisibilityChange = useCallback(() => {
+    if (!isEnabled) return;
+
+    if (!document.hidden) {
+      debugLog("[Idle Detection] Tab became active", {
+        timestamp: new Date().toISOString(),
+      });
+
+      // Send keep-alive (axios layer handles throttling)
+      void sendKeepAliveNow();
+    }
+  }, [isEnabled, sendKeepAliveNow]);
+
+  // Create throttled handler using lodash to reduce JS overhead from high-frequency events
+  // useMemo ensures stable reference and proper cleanup
+  const throttledHandler = useMemo(
+    () =>
+      throttle(handleActivity, IDLE_DETECTION_CONFIG.EVENT_THROTTLE_MS, {
+        leading: true,
+        trailing: true,
+      }),
+    [handleActivity],
+  );
+
+  useEffect(() => {
+    if (!isEnabled) {
+      debugLog("[Idle Detection] Disabled", {
+        idleTimeout: idleTimeout,
+        reason:
+          idleTimeout === undefined
+            ? "idle_timeout not configured on server"
+            : idleTimeout === 0
+              ? "idle_timeout is 0"
+              : "disconnected",
+      });
+      return;
+    }
+
+    debugLog("[Idle Detection] Initialized", {
+      enabled: true,
+      idleTimeout: `${idleTimeout}s`,
+      eventThrottle: `${IDLE_DETECTION_CONFIG.EVENT_THROTTLE_MS}ms`,
+      apiThrottle: "3s (axios layer)",
+      monitoredEvents: IDLE_DETECTION_CONFIG.ACTIVITY_EVENTS.join(", "),
+    });
+
+    // Register activity event listeners with throttled handler
+    IDLE_DETECTION_CONFIG.ACTIVITY_EVENTS.forEach((eventType) => {
+      window.addEventListener(eventType, throttledHandler, { passive: true });
+    });
+
+    // Register visibility change listener (not throttled - immediate response needed)
+    document.addEventListener("visibilitychange", handleVisibilityChange);
+
+    // Cleanup function
+    return () => {
+      debugLog("[Idle Detection] Cleanup - removing event listeners");
+      IDLE_DETECTION_CONFIG.ACTIVITY_EVENTS.forEach((eventType) => {
+        window.removeEventListener(eventType, throttledHandler);
+      });
+      document.removeEventListener("visibilitychange", handleVisibilityChange);
+      throttledHandler.cancel(); // Cancel any pending throttled calls
+    };
+  }, [isEnabled, throttledHandler, handleVisibilityChange, idleTimeout]);
+}

package/recce-source/js/src/lib/hooks/useModelColumns.tsx

@@ -0,0 +1,113 @@
+import _ from "lodash";
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { LineageGraphNode } from "@/components/lineage/lineage";
+import { getModelInfo, NodeColumnData, NodeData } from "../api/info";
+import { useLineageGraphContext } from "./LineageGraphContext";
+
+export function extractColumns(node: LineageGraphNode) {
+  function getColumns(nodeData: NodeData | undefined) {
+    return nodeData?.columns
+      ? Object.values(nodeData.columns).filter((c) => c != null)
+      : [];
+  }
+
+  const baseColumns = getColumns(node.data.data.base);
+  const currentColumns = getColumns(node.data.data.current);
+
+  return unionColumns(baseColumns, currentColumns);
+}
+
+export function unionColumns(
+  baseColumns: NodeColumnData[],
+  currentColumns: NodeColumnData[],
+) {
+  const union: NodeColumnData[] = [];
+  baseColumns.forEach((column) => {
+    if (!union.some((c) => c.name === column.name)) {
+      union.push(column);
+    }
+  });
+  currentColumns.forEach((column) => {
+    if (!union.some((c) => c.name === column.name)) {
+      union.push(column);
+    }
+  });
+
+  return union;
+}
+
+const useModelColumns = (model: string | undefined) => {
+  const { lineageGraph } = useLineageGraphContext();
+
+  const node = _.find(lineageGraph?.nodes, {
+    data: {
+      name: model,
+    },
+  });
+
+  const nodeColumns = useMemo(() => {
+    return node ? extractColumns(node) : [];
+  }, [node]);
+
+  const [columns, setColumns] = useState<NodeColumnData[]>([]);
+  const [primaryKey, setPrimaryKey] = useState<string>();
+  const [isLoading, setIsLoading] = useState<boolean>(true);
+  const [error, setError] = useState<Error | null>(null);
+  const [prevNodeColumns, setPrevNodeColumns] = useState<NodeColumnData[]>([]);
+  const [prevNodeId, setPrevNodeId] = useState(node?.id);
+
+  const nodePrimaryKey = node ? node.data.data.current?.primary_key : undefined;
+
+  const fetchData = useCallback(async () => {
+    if (!node) {
+      return;
+    }
+    try {
+      const data = await getModelInfo(node.id);
+      const modelInfo = data.model;
+      if (!modelInfo.base.columns || !modelInfo.current.columns) {
+        setColumns([]);
+        return;
+      }
+      setPrimaryKey(modelInfo.current.primary_key);
+      const baseColumns = Object.values(modelInfo.base.columns);
+      const currentColumns = Object.values(modelInfo.current.columns);
+      setColumns(unionColumns(baseColumns, currentColumns));
+    } catch (error) {
+      setError(error as Error);
+    }
+  }, [node]);
+
+  // Adjust state during render when node changes
+  if (nodeColumns !== prevNodeColumns || node?.id !== prevNodeId) {
+    setPrevNodeColumns(nodeColumns);
+    setPrevNodeId(node?.id);
+
+    if (nodeColumns.length > 0) {
+      setColumns(nodeColumns);
+      setPrimaryKey(nodePrimaryKey);
+      setIsLoading(false);
+    } else if (node?.id === undefined) {
+      setColumns([]);
+      setIsLoading(false);
+    }
+    // Note: fetchData case is handled separately in effect below
+  }
+
+  // Fetch data effect - only runs when we need to fetch
+  useEffect(() => {
+    if (nodeColumns.length === 0 && node?.id !== undefined) {
+      // fetchData() is a legitimate side effect, leaving
+      // eslint-disable-next-line react-hooks/set-state-in-effect
+      fetchData().catch((e: unknown) => {
+        // error is already handled in fetchData()
+        console.error(e);
+      });
+      setIsLoading(false);
+    }
+  }, [fetchData, node?.id, nodeColumns]);
+
+  return { columns, primaryKey, isLoading, error };
+};
+
+export default useModelColumns;

package/recce-source/js/src/lib/hooks/useRecceInstanceInfo.tsx

@@ -0,0 +1,13 @@
+import { useQuery } from "@tanstack/react-query";
+import { cacheKeys } from "../api/cacheKeys";
+import { getRecceInstanceInfo, RecceInstanceInfo } from "../api/instanceInfo";
+import { useApiConfig } from "./ApiConfigContext";
+
+export const useRecceInstanceInfo = () => {
+  const { apiClient } = useApiConfig();
+
+  return useQuery<RecceInstanceInfo>({
+    queryKey: cacheKeys.instanceInfo(),
+    queryFn: () => getRecceInstanceInfo(apiClient),
+  });
+};

package/recce-source/js/src/lib/hooks/useRecceServerFlag.tsx

@@ -0,0 +1,13 @@
+import { useQuery } from "@tanstack/react-query";
+import { cacheKeys } from "../api/cacheKeys";
+import { getServerFlag, RecceServerFlags } from "../api/flag";
+import { useApiConfig } from "./ApiConfigContext";
+
+export const useRecceServerFlag = () => {
+  const { apiClient } = useApiConfig();
+
+  return useQuery<RecceServerFlags>({
+    queryKey: cacheKeys.flag(),
+    queryFn: () => getServerFlag(apiClient),
+  });
+};

package/recce-source/js/src/lib/hooks/useRun.tsx

@@ -0,0 +1,89 @@
+import { useQuery } from "@tanstack/react-query";
+import { useCallback, useEffect, useState } from "react";
+import {
+  findByRunType,
+  RegistryEntry,
+  runTypeHasRef,
+} from "@/components/run/registry";
+import { cacheKeys } from "@/lib/api/cacheKeys";
+import { cancelRun, waitRun } from "@/lib/api/runs";
+import { Run } from "../api/types";
+import { useApiConfig } from "./ApiConfigContext";
+import { useRunsAggregated } from "./LineageGraphContext";
+
+interface UseRunResult {
+  run?: Run;
+  aborting: boolean;
+  isRunning: boolean;
+  error: Error | null;
+  onCancel: () => Promise<void>;
+  RunResultView?: RegistryEntry["RunResultView"] | undefined;
+}
+
+export const useRun = (runId?: string): UseRunResult => {
+  const { apiClient } = useApiConfig();
+  const [isRunning, setIsRunning] = useState(false);
+  const [aborting, setAborting] = useState(false);
+  const [, refetchRunsAggregated] = useRunsAggregated();
+
+  const { error, data: run } = useQuery({
+    queryKey: cacheKeys.run(runId ?? ""),
+    queryFn: async () => {
+      return await waitRun(runId ?? "", isRunning ? 2 : 0, apiClient);
+    },
+    enabled: !!runId,
+    refetchInterval: isRunning ? 50 : false,
+    retry: false,
+  });
+
+  // Track previous run state to detect changes
+  const [prevRun, setPrevRun] = useState(run);
+  const [prevError, setPrevError] = useState(error);
+
+  // Adjust isRunning during render when run/error state changes
+  if (run !== prevRun || error !== prevError) {
+    setPrevRun(run);
+    setPrevError(error);
+
+    if (error || run?.result || run?.error) {
+      setIsRunning(false);
+    } else if (run?.status === "running") {
+      setIsRunning(true);
+    }
+  }
+
+  // Side effect: refetch aggregated runs when row count runs complete
+  useEffect(() => {
+    if (
+      (error || run?.result || run?.error) &&
+      (run?.type === "row_count_diff" || run?.type === "row_count")
+    ) {
+      refetchRunsAggregated();
+    }
+  }, [run, error, refetchRunsAggregated]);
+
+  const onCancel = useCallback(async () => {
+    setAborting(true);
+    if (!runId) {
+      return;
+    }
+
+    await cancelRun(runId, apiClient);
+    return;
+  }, [runId, apiClient]);
+
+  let RunResultView: RegistryEntry["RunResultView"] | undefined;
+  if (run && runTypeHasRef(run.type)) {
+    RunResultView = findByRunType(run.type)
+      .RunResultView as RegistryEntry["RunResultView"];
+  }
+
+  return {
+    run,
+    isRunning,
+    aborting,
+    error,
+    onCancel,
+    RunResultView,
+  };
+};

package/recce-source/js/src/lib/hooks/useThemeColors.ts

@@ -0,0 +1,115 @@
+"use client";
+
+import { useTheme as useMuiTheme } from "@mui/material/styles";
+import { useTheme as useNextTheme } from "next-themes";
+import { useEffect, useState } from "react";
+import { colors } from "@/components/ui/mui-theme";
+
+/**
+ * Theme-aware color utility hook
+ *
+ * Uses next-themes to determine dark/light mode, which is more reliable
+ * when the host app uses MUI CSS variables mode with nested ThemeProviders.
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { isDark, background, text, border } = useThemeColors();
+ *
+ *   return (
+ *     <Box sx={{
+ *       bgcolor: background.paper,
+ *       color: text.primary,
+ *       borderColor: border.default,
+ *     }}>
+ *       Content
+ *     </Box>
+ *   );
+ * }
+ * ```
+ */
+export function useThemeColors() {
+  const muiTheme = useMuiTheme();
+  const { resolvedTheme } = useNextTheme();
+  const [mounted, setMounted] = useState(false);
+
+  useEffect(() => {
+    setMounted(true);
+  }, []);
+
+  // Use next-themes to determine dark mode (more reliable with CSS variables mode)
+  const isDark = mounted ? resolvedTheme === "dark" : false;
+
+  return {
+    /** Whether the current theme is dark mode */
+    isDark,
+
+    /** MUI theme object for direct access when needed */
+    theme: muiTheme,
+
+    /** Background colors */
+    background: {
+      /** Default page background */
+      default: isDark ? colors.neutral[900] : colors.white,
+      /** Paper/card background */
+      paper: isDark ? colors.neutral[800] : colors.white,
+      /** Subtle background for slight elevation (e.g., hover states, inputs) */
+      subtle: isDark ? colors.neutral[800] : colors.neutral[50],
+      /** Emphasized background for higher contrast areas */
+      emphasized: isDark ? colors.neutral[700] : colors.neutral[100],
+    },
+
+    /** Text colors */
+    text: {
+      /** Primary text color */
+      primary: isDark ? colors.neutral[50] : colors.neutral[900],
+      /** Secondary/muted text color */
+      secondary: isDark ? colors.neutral[400] : colors.neutral[600],
+      /** Disabled text color */
+      disabled: isDark ? colors.neutral[500] : colors.neutral[400],
+      /** Inverted text (for use on dark backgrounds in light mode, etc.) */
+      inverted: isDark ? colors.neutral[900] : colors.neutral[50],
+    },
+
+    /** Border colors */
+    border: {
+      /** Light border for subtle separations */
+      light: isDark ? colors.neutral[700] : colors.neutral[200],
+      /** Default border color */
+      default: isDark ? colors.neutral[600] : colors.neutral[300],
+      /** Strong border for emphasis */
+      strong: isDark ? colors.neutral[500] : colors.neutral[400],
+    },
+
+    /** Status/semantic colors */
+    status: {
+      /** Added/success backgrounds */
+      added: {
+        bg: isDark ? colors.green[900] : colors.green[100],
+        text: isDark ? colors.neutral[50] : colors.neutral[900],
+      },
+      /** Removed/error backgrounds */
+      removed: {
+        bg: isDark ? colors.red[950] : colors.red[200],
+        text: isDark ? colors.neutral[50] : colors.neutral[900],
+      },
+      /** Modified/warning backgrounds */
+      modified: {
+        bg: isDark ? colors.yellow[900] : colors.amber[100],
+        text: isDark ? colors.neutral[50] : colors.neutral[900],
+      },
+    },
+
+    /** Interactive element colors */
+    interactive: {
+      /** Hover state background */
+      hover: isDark ? colors.neutral[700] : colors.neutral[100],
+      /** Active/pressed state background */
+      active: isDark ? colors.neutral[600] : colors.neutral[200],
+      /** Focus ring color */
+      focus: colors.iochmara[500],
+    },
+  };
+}
+
+export type ThemeColors = ReturnType<typeof useThemeColors>;

package/recce-source/js/src/lib/mergeKeys.test.ts

@@ -0,0 +1,89 @@
+import { mergeKeys, mergeKeysWithStatus } from "./mergeKeys";
+
+test("should merge keys from base and target arrays while preserving order", () => {
+  const base = ["id", "name", "age", "email"];
+  const curr = ["name", "age", "city"];
+
+  const result = mergeKeysWithStatus(base, curr);
+
+  // The expected result after merging is: ['id', 'name', 'age', 'city', 'email']
+  expect(result).toEqual({
+    id: "removed",
+    name: undefined,
+    age: undefined,
+    email: "removed",
+    city: "added",
+  });
+});
+
+test("should merge keys from base and target arrays while preserving order (case 2)", () => {
+  const base = ["id", "name", "age", "city"];
+  const curr = ["id", "fullname", "age", "city"];
+
+  const result = mergeKeysWithStatus(base, curr);
+  const expected = {
+    id: undefined,
+    name: "removed",
+    fullname: "added",
+    age: undefined,
+    city: undefined,
+  };
+
+  expect(Object.keys(result)).toEqual(Object.keys(expected));
+  expect(result).toEqual(expected);
+});
+
+test("should handle empty arrays", () => {
+  const base = [] as string[];
+  const curr = ["name", "age", "city"];
+
+  const result = mergeKeys(base, curr);
+
+  // The expected result is the target array itself when the base array is empty
+  expect(result).toEqual(curr);
+});
+
+test("should handle duplicate keys in base and target arrays", () => {
+  const base = ["id", "name", "age", "email"];
+  const curr = ["name", "age", "id", "city", "name"];
+
+  const result = mergeKeysWithStatus(base, curr);
+  const expected = {
+    name: undefined,
+    age: undefined,
+    id: "reordered",
+    email: "removed",
+    city: "added",
+  };
+
+  expect(Object.keys(result)).toEqual(Object.keys(expected));
+  expect(result).toEqual(expected);
+});
+
+test("should handle reoder keys", () => {
+  const base = ["address", "id", "name", "age", "city"];
+  const curr = ["email", "city", "age", "name", "id"];
+
+  const result = mergeKeysWithStatus(base, curr);
+  const expected = {
+    address: "removed",
+    email: "added",
+    city: undefined,
+    age: "reordered",
+    name: "reordered",
+    id: "reordered",
+  };
+
+  expect(Object.keys(result)).toEqual(Object.keys(expected));
+  expect(result).toEqual(expected);
+});
+
+test("should handle both arrays having the same keys", () => {
+  const base = ["id", "name", "age"];
+  const curr = ["id", "name", "age"];
+
+  const result = mergeKeys(base, curr);
+
+  // The expected result after merging is the same as the base array
+  expect(result).toEqual(base);
+});