@datarecce/ui 0.1.41 → 0.2.0

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

@@ -1,45 +0,0 @@
-import { useState } from "react";
-import { toaster } from "@/components/ui/toaster";
-
-export function useGuideToast(options: {
-  guideId: string;
-  description: string;
-  externalLink?: string;
-  externalLinkText?: string;
-  onExternalLinkClick?: () => void;
-}) {
-  const [toastId, setToastId] = useState<string | undefined>(undefined);
-  const { guideId, description, externalLinkText, onExternalLinkClick } =
-    options;
-
-  function guideToast() {
-    if (toastId != null) {
-      // Don't show the toast again if it's already active
-      return;
-    }
-
-    setToastId(
-      toaster.create({
-        id: guideId,
-        duration: 3000,
-        type: "success",
-        description: description,
-        action: {
-          label: externalLinkText ?? "link",
-          onClick: () => {
-            if (onExternalLinkClick) {
-              onExternalLinkClick();
-            }
-          },
-        },
-      }),
-    );
-  }
-
-  return {
-    guideToast: guideToast,
-    closeGuideToast: () => {
-      if (toastId) toaster.dismiss(toastId);
-    },
-  };
-}

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

@@ -1,185 +0,0 @@
-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

@@ -1,113 +0,0 @@
-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

@@ -1,13 +0,0 @@
-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

@@ -1,13 +0,0 @@
-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

@@ -1,89 +0,0 @@
-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

@@ -1,115 +0,0 @@
-"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

@@ -1,89 +0,0 @@
-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);
-});