@datarecce/ui 0.1.30 → 0.1.31

package/src/api/index.ts

@@ -0,0 +1,32 @@
+/**
+ * API Module
+ *
+ * This module provides API client utilities and functions
+ * for interacting with the Recce backend.
+ */
+
+// API Client
+export { axiosClient, reactQueryClient } from '@/lib/api/axiosClient';
+
+// API Functions
+export * from '@/lib/api/adhocQuery';
+export * from '@/lib/api/checks';
+export * from '@/lib/api/cll';
+export * from '@/lib/api/connectToCloud';
+export * from '@/lib/api/flag';
+export * from '@/lib/api/info';
+export * from '@/lib/api/lineagecheck';
+export * from '@/lib/api/models';
+export * from '@/lib/api/profile';
+export * from '@/lib/api/rowcount';
+export * from '@/lib/api/runs';
+export * from '@/lib/api/schemacheck';
+export * from '@/lib/api/select';
+export * from '@/lib/api/state';
+export * from '@/lib/api/user';
+export * from '@/lib/api/valuediff';
+export * from '@/lib/api/version';
+
+// Storage Keys
+export * from '@/lib/api/localStorageKeys';
+export * from '@/lib/api/sessionStorageKeys';

package/src/components/index.ts

@@ -0,0 +1,154 @@
+/**
+ * Components Module
+ *
+ * This module re-exports React components from the Recce submodule.
+ * Components are organized by feature area for easy discovery.
+ */
+
+// =============================================================================
+// Core / Foundation
+// =============================================================================
+export {
+  MuiProvider,
+  default as MuiProviderDefault,
+} from "@/components/ui/mui-provider";
+export { Toaster, ToasterProvider, useToaster } from "@/components/ui/toaster";
+export { ErrorBoundary } from "@/components/errorboundary/ErrorBoundary";
+
+// =============================================================================
+// Layout
+// =============================================================================
+export { HSplit, VSplit } from "@/components/split/Split";
+export { ScreenshotBox } from "@/components/screenshot/ScreenshotBox";
+
+// =============================================================================
+// Lineage
+// =============================================================================
+export { LineagePage } from "@/components/lineage/LineagePage";
+export { LineageView } from "@/components/lineage/LineageView";
+export {
+  LineageViewContext,
+  useLineageViewContext,
+} from "@/components/lineage/LineageViewContext";
+export { LineageViewTopBar } from "@/components/lineage/LineageViewTopBar";
+export { GraphNode } from "@/components/lineage/GraphNode";
+export { default as GraphEdge } from "@/components/lineage/GraphEdge";
+export { GraphColumnNode } from "@/components/lineage/GraphColumnNode";
+export { NodeView } from "@/components/lineage/NodeView";
+export { NodeSqlView } from "@/components/lineage/NodeSqlView";
+export {
+  ResourceTypeTag,
+  ModelRowCount,
+  RowCountDiffTag,
+  type RowCountDiffTagProps,
+  type RowCountTagProps,
+} from "@/components/lineage/NodeTag";
+export { default as SetupConnectionBanner } from "@/components/lineage/SetupConnectionBanner";
+
+// =============================================================================
+// Query
+// =============================================================================
+export { QueryPage } from "@/components/query/QueryPage";
+export { QueryForm } from "@/components/query/QueryForm";
+export { default as SqlEditor } from "@/components/query/SqlEditor";
+export { QueryResultView } from "@/components/query/QueryResultView";
+export { QueryDiffResultView } from "@/components/query/QueryDiffResultView";
+export { DiffText } from "@/components/query/DiffText";
+export { default as SetupConnectionGuide } from "@/components/query/SetupConnectionGuide";
+
+// =============================================================================
+// Editor
+// =============================================================================
+export { default as CodeEditor } from "@/components/editor/CodeEditor";
+export { default as DiffEditor } from "@/components/editor/DiffEditor";
+
+// =============================================================================
+// Schema
+// =============================================================================
+export { SchemaView } from "@/components/schema/SchemaView";
+export { ColumnNameCell } from "@/components/schema/ColumnNameCell";
+
+// =============================================================================
+// Check / Checklist
+// =============================================================================
+export { CheckList } from "@/components/check/CheckList";
+export { CheckDetail } from "@/components/check/CheckDetail";
+export { CheckBreadcrumb } from "@/components/check/CheckBreadcrumb";
+export { CheckDescription } from "@/components/check/CheckDescription";
+export { CheckEmptyState } from "@/components/check/CheckEmptyState";
+export { LineageDiffView } from "@/components/check/LineageDiffView";
+export { SchemaDiffView } from "@/components/check/SchemaDiffView";
+
+// =============================================================================
+// Run
+// =============================================================================
+export { RunPage } from "@/components/run/RunPage";
+export { RunList } from "@/components/run/RunList";
+export { RunView } from "@/components/run/RunView";
+export { RunModal } from "@/components/run/RunModal";
+export { RunToolbar } from "@/components/run/RunToolbar";
+export { RunResultPane } from "@/components/run/RunResultPane";
+export { RunStatusAndDate } from "@/components/run/RunStatusAndDate";
+
+// =============================================================================
+// Data Diff Components
+// =============================================================================
+
+// Profile Diff
+export { ProfileDiffForm } from "@/components/profile/ProfileDiffForm";
+export { ProfileDiffResultView } from "@/components/profile/ProfileDiffResultView";
+
+// Value Diff
+export { ValueDiffForm } from "@/components/valuediff/ValueDiffForm";
+export { ValueDiffResultView } from "@/components/valuediff/ValueDiffResultView";
+export { ValueDiffDetailResultView } from "@/components/valuediff/ValueDiffDetailResultView";
+
+// Histogram Diff
+export { HistogramDiffForm } from "@/components/histogram/HistogramDiffForm";
+export { HistogramDiffResultView } from "@/components/histogram/HistogramDiffResultView";
+
+// Top-K Diff
+export { TopKDiffForm } from "@/components/top-k/TopKDiffForm";
+export { TopKDiffResultView } from "@/components/top-k/TopKDiffResultView";
+
+// Row Count Diff
+export { RowCountDiffResultView } from "@/components/rowcount/RowCountDiffResultView";
+
+// =============================================================================
+// Data Grid
+// =============================================================================
+export { ScreenshotDataGrid } from "@/components/data-grid/ScreenshotDataGrid";
+
+// =============================================================================
+// Charts
+// =============================================================================
+export { HistogramChart } from "@/components/charts/HistogramChart";
+export { TopKSummaryList } from "@/components/charts/TopKSummaryList";
+export { SquareIcon } from "@/components/charts/SquareIcon";
+
+// =============================================================================
+// Summary
+// =============================================================================
+export { default as SummaryView } from "@/components/summary/SummaryView";
+export { ChangeSummary } from "@/components/summary/ChangeSummary";
+export { SchemaSummary } from "@/components/summary/SchemaSummary";
+
+// =============================================================================
+// App Components
+// =============================================================================
+export { EnvInfo } from "@/components/app/EnvInfo";
+export { default as TopBar } from "../../recce-source/js/app/(mainComponents)/TopBar";
+export { default as NavBar } from "../../recce-source/js/app/(mainComponents)/NavBar";
+export { default as DisplayModeToggle } from "../../recce-source/js/app/(mainComponents)/DisplayModeToggle";
+export { default as RecceVersionBadge } from "../../recce-source/js/app/(mainComponents)/RecceVersionBadge";
+
+// =============================================================================
+// Shared / Utilities
+// =============================================================================
+export { default as HistoryToggle } from "@/components/shared/HistoryToggle";
+export { IdleTimeoutBadge } from "@/components/timeout/IdleTimeoutBadge";
+
+// =============================================================================
+// Icons
+// =============================================================================
+export * from "@/components/icons";

package/src/global.d.ts

@@ -0,0 +1,14 @@
+declare module '*.svg' {
+  const content: any;
+  export default content;
+}
+
+declare module '*.css' {
+  const content: { [className: string]: string };
+  export default content;
+}
+
+declare module 'public/imgs/reload-image.svg' {
+  const content: any;
+  export default content;
+}

package/src/hooks/index.ts

@@ -0,0 +1,56 @@
+/**
+ * Hooks Module
+ *
+ * This module exports custom React hooks from the Recce library.
+ */
+
+// Custom Hooks
+export { useRecceInstanceInfo } from '@/lib/hooks/useRecceInstanceInfo';
+export { useCheckToast } from '@/lib/hooks/useCheckToast';
+export { useClipBoardToast } from '@/lib/hooks/useClipBoardToast';
+
+// Re-export component-specific hooks
+export { useLineageViewContext } from '@/components/lineage/LineageViewContext';
+export { default as useValueDiffAlertDialog } from '@/components/lineage/useValueDiffAlertDialog';
+
+// Context Providers
+export { default as RecceContextProvider } from '@/lib/hooks/RecceContextProvider';
+export { RecceInstanceInfoProvider, useRecceInstanceContext } from '@/lib/hooks/RecceInstanceContext';
+export { LineageGraphContextProvider, useLineageGraphContext, useRunsAggregated } from '@/lib/hooks/LineageGraphContext';
+export { RecceShareStateContextProvider, useRecceShareStateContext } from '@/lib/hooks/RecceShareStateContext';
+export { RecceQueryContextProvider, RowCountStateContextProvider, useRecceQueryContext, useRowCountStateContext } from '@/lib/hooks/RecceQueryContext';
+export {
+  RecceActionContext,
+  RecceActionContextProvider,
+  useRecceActionContext,
+  type RecceActionContextType,
+} from '@/lib/hooks/RecceActionContext';
+export { RecceCheckContextProvider, useRecceCheckContext } from '@/lib/hooks/RecceCheckContext';
+export { IdleTimeoutProvider, useIdleTimeout } from '@/lib/hooks/IdleTimeoutContext';
+
+// API Configuration
+export {
+  ApiConfigProvider,
+  useApiConfig,
+  useApiClient,
+  useApiConfigSafe,
+  type ApiConfig
+} from '@/lib/hooks/ApiConfigContext';
+
+// Route Configuration (for recce-cloud path prefixing)
+export {
+  RouteConfigProvider,
+  useRouteConfig,
+  useRouteConfigSafe,
+  type RouteConfig,
+  type RouteConfigContextType,
+} from '../lib/hooks/RouteConfigContext';
+
+// App Router hooks (custom version with RouteConfigContext support)
+export {
+  useAppLocation,
+  useAppLocationWithSearch,
+  useAppRoute,
+  useAppNavigation,
+  navigateTo,
+} from '../lib/hooks/useAppRouter';

package/src/index.ts

@@ -0,0 +1,17 @@
+/**
+ * @datarecce/ui - Recce UI Components Library
+ *
+ * Main entry point for the Recce UI component library.
+ * This library provides reusable React components for building
+ * data validation and review interfaces.
+ */
+
+// Re-export everything from submodules
+export * from "./components";
+export * from "./api";
+export * from "./hooks";
+export * from "./types";
+export * from "./theme";
+
+// Export a version constant
+export const VERSION = "0.1.0";

package/src/lib/hooks/RouteConfigContext.ts

@@ -0,0 +1,139 @@
+"use client";
+
+import React, { createContext, useCallback, useContext, useMemo } from "react";
+
+/**
+ * Route Configuration for path prefix customization.
+ *
+ * This context allows recce-cloud to configure a base path prefix
+ * for all navigation within OSS components.
+ *
+ * Default behavior (OSS):
+ * - basePath: "" (uses absolute paths like /query, /checks)
+ *
+ * Cloud usage example:
+ * - basePath: "/oss/abc123" or "/preview/abc123"
+ * - Navigation to "/query" becomes "/oss/abc123/query"
+ */
+
+export interface RouteConfig {
+  /**
+   * Base path prefix for navigation.
+   * For OSS: "" (empty string, uses absolute paths like /query)
+   * For Cloud: "/oss/<sessionId>" or "/preview/<sessionId>"
+   */
+  basePath: string;
+}
+
+export interface RouteConfigContextType extends RouteConfig {
+  /**
+   * Resolves a path with the base path prefix.
+   * @param path - The path to resolve (e.g., "/query")
+   * @returns The resolved path (e.g., "/oss/abc123/query")
+   */
+  resolvePath: (path: string) => string;
+}
+
+const defaultConfig: RouteConfig = {
+  basePath: "",
+};
+
+const RouteConfigContext = createContext<RouteConfigContextType | null>(null);
+
+interface RouteConfigProviderProps extends Partial<RouteConfig> {
+  children: React.ReactNode;
+}
+
+/**
+ * Provider for route configuration.
+ *
+ * Wrap your application (or RecceContextProvider) with this provider
+ * to configure path prefixes for navigation.
+ *
+ * @example
+ * // In recce-cloud
+ * <RouteConfigProvider basePath={`/oss/${sessionId}`}>
+ *   <RecceContextProvider>
+ *     {children}
+ *   </RecceContextProvider>
+ * </RouteConfigProvider>
+ */
+export function RouteConfigProvider({
+  children,
+  basePath = defaultConfig.basePath,
+}: RouteConfigProviderProps) {
+  const resolvePath = useCallback(
+    (path: string): string => {
+      // If no basePath configured, return path as-is (OSS mode)
+      if (!basePath) {
+        return path;
+      }
+
+      // Handle paths that already start with the basePath (avoid double-prefixing)
+      if (path.startsWith(basePath)) {
+        return path;
+      }
+
+      // Handle absolute URLs (http://, https://, etc.) - don't prefix
+      if (path.match(/^https?:\/\//)) {
+        return path;
+      }
+
+      // Handle hash-only paths - don't prefix
+      if (path.startsWith("#")) {
+        return path;
+      }
+
+      // Ensure proper joining (no double slashes)
+      const cleanBasePath = basePath.endsWith("/")
+        ? basePath.slice(0, -1)
+        : basePath;
+      const cleanPath = path.startsWith("/") ? path : `/${path}`;
+
+      return `${cleanBasePath}${cleanPath}`;
+    },
+    [basePath],
+  );
+
+  const contextValue: RouteConfigContextType = useMemo(
+    () => ({
+      basePath,
+      resolvePath,
+    }),
+    [basePath, resolvePath],
+  );
+
+  return React.createElement(
+    RouteConfigContext.Provider,
+    { value: contextValue },
+    children,
+  );
+}
+
+// Default context for OSS mode (no prefix)
+const defaultRouteConfigContext: RouteConfigContextType = {
+  basePath: "",
+  resolvePath: (path: string) => path,
+};
+
+/**
+ * Hook to access route configuration.
+ *
+ * When used outside RouteConfigProvider, returns default config
+ * (for OSS backward compatibility).
+ *
+ * @returns RouteConfigContextType with basePath and resolvePath function
+ */
+export function useRouteConfig(): RouteConfigContextType {
+  const context = useContext(RouteConfigContext);
+  // Return default config if outside provider (OSS mode)
+  return context ?? defaultRouteConfigContext;
+}
+
+/**
+ * Safe hook that returns null if context not available.
+ * Useful for components that need to detect if RouteConfigProvider is present.
+ */
+export function useRouteConfigSafe(): RouteConfigContextType | null {
+  return useContext(RouteConfigContext);
+}

package/src/lib/hooks/useAppRouter.ts

@@ -0,0 +1,240 @@
+/**
+ * useAppRouter - Navigation utilities for Next.js App Router with RouteConfig support
+ *
+ * This is a custom version that wraps the OSS useAppRouter to add
+ * RouteConfigContext support for path prefixing in recce-cloud.
+ *
+ * The key difference from OSS:
+ * - setLocation() automatically prefixes paths with the configured basePath
+ * - This allows OSS components to use setLocation("/query") while
+ *   recce-cloud can configure basePath="/oss/abc123" to get "/oss/abc123/query"
+ */
+
+"use client";
+
+import {
+  useParams,
+  usePathname,
+  useRouter,
+  useSearchParams,
+} from "next/navigation";
+import { useCallback, useMemo } from "react";
+import { useRouteConfig } from "./RouteConfigContext";
+
+interface NavigateOptions {
+  replace?: boolean;
+  scroll?: boolean;
+}
+
+/**
+ * Hook that provides Wouter-compatible location API using Next.js App Router
+ * with RouteConfigContext support for path prefixing.
+ *
+ * NOTE: This returns only the pathname (not search params) to avoid
+ * triggering Suspense boundaries on every navigation.
+ *
+ * @returns [pathname, setLocation] tuple similar to Wouter's useLocation
+ *
+ * @example
+ * const [location, setLocation] = useAppLocation();
+ * setLocation("/checks?id=123"); // In cloud mode with basePath="/oss/abc123"
+ *                                 // navigates to "/oss/abc123/checks?id=123"
+ */
+export function useAppLocation(): [
+  string,
+  (to: string, options?: NavigateOptions) => void,
+] {
+  const router = useRouter();
+  const pathname = usePathname();
+  const { resolvePath } = useRouteConfig();
+
+  // Navigation function compatible with Wouter's setLocation
+  // Automatically applies basePath prefix from RouteConfigContext
+  const setLocation = useCallback(
+    (to: string, options?: NavigateOptions) => {
+      // Separate path and query string for proper handling
+      const [pathPart, queryPart] = to.split("?");
+      const resolvedPath = resolvePath(pathPart);
+      const fullPath = queryPart ? `${resolvedPath}?${queryPart}` : resolvedPath;
+
+      if (options?.replace) {
+        router.replace(fullPath, { scroll: options?.scroll ?? true });
+      } else {
+        router.push(fullPath, { scroll: options?.scroll ?? true });
+      }
+    },
+    [router, resolvePath],
+  );
+
+  return [pathname, setLocation];
+}
+
+/**
+ * Hook that includes search params in the location string.
+ * Also supports RouteConfigContext path prefixing.
+ *
+ * WARNING: This hook uses useSearchParams() which triggers Suspense.
+ * Only use this in components that are wrapped in a <Suspense> boundary,
+ * or in leaf components where suspension is acceptable.
+ *
+ * @returns [fullLocation, setLocation] tuple with search params included
+ */
+export function useAppLocationWithSearch(): [
+  string,
+  (to: string, options?: NavigateOptions) => void,
+] {
+  const router = useRouter();
+  const pathname = usePathname();
+  const searchParams = useSearchParams();
+  const { resolvePath } = useRouteConfig();
+
+  // Construct full location string including search params
+  const location = useMemo(() => {
+    const search = searchParams?.toString();
+    return search ? `${pathname}?${search}` : pathname;
+  }, [pathname, searchParams]);
+
+  // Navigation function with RouteConfigContext support
+  const setLocation = useCallback(
+    (to: string, options?: NavigateOptions) => {
+      const [pathPart, queryPart] = to.split("?");
+      const resolvedPath = resolvePath(pathPart);
+      const fullPath = queryPart ? `${resolvedPath}?${queryPart}` : resolvedPath;
+
+      if (options?.replace) {
+        router.replace(fullPath, { scroll: options?.scroll ?? true });
+      } else {
+        router.push(fullPath, { scroll: options?.scroll ?? true });
+      }
+    },
+    [router, resolvePath],
+  );
+
+  return [location, setLocation];
+}
+
+/**
+ * Hook to check if current path matches a pattern
+ * Similar to Wouter's useRoute
+ *
+ * @param pattern - The route pattern to match (e.g., "/checks/:checkId")
+ * @returns [isMatch, params] tuple
+ *
+ * @example
+ * const [isMatch, params] = useAppRoute("/checks/:checkId");
+ * if (isMatch) {
+ *   console.log(params.checkId); // "abc-123"
+ * }
+ */
+export function useAppRoute(
+  pattern: string,
+): [boolean, Record<string, string>] {
+  const pathname = usePathname();
+  const params = useParams();
+
+  const isMatch = useMemo(() => {
+    // Convert Next.js dynamic route pattern to regex
+    // /checks/[checkId] -> /checks/:checkId -> /checks/([^/]+)
+    const regexPattern = pattern
+      .replace(/:\w+/g, "([^/]+)") // :param -> capture group
+      .replace(/\*/g, ".*"); // * -> wildcard
+
+    const regex = new RegExp(`^${regexPattern}$`);
+    return regex.test(pathname);
+  }, [pattern, pathname]);
+
+  // Convert Next.js params to plain object
+  const paramsObj = useMemo(() => {
+    if (!params) return {};
+    return Object.fromEntries(
+      Object.entries(params).map(([key, value]) => [
+        key,
+        Array.isArray(value) ? value.join("/") : value,
+      ]),
+    );
+  }, [params]);
+
+  return [isMatch, paramsObj as Record<string, string>];
+}
+
+/**
+ * Imperative navigation function for use outside React components
+ * Use sparingly - prefer useAppLocation hook in components
+ *
+ * NOTE: This function does NOT support RouteConfigContext because
+ * it's used outside of React component tree. If you need path prefixing,
+ * use useAppLocation hook instead.
+ *
+ * @example
+ * // In an event handler or utility function
+ * import { navigateTo } from "@/lib/hooks/useAppRouter";
+ * navigateTo("/checks?id=123");
+ */
+export function navigateTo(path: string, replace = false): void {
+  if (typeof window !== "undefined") {
+    if (replace) {
+      window.history.replaceState(null, "", path);
+    } else {
+      window.history.pushState(null, "", path);
+    }
+    // Trigger Next.js to recognize the navigation
+    window.dispatchEvent(new PopStateEvent("popstate"));
+  }
+}
+
+/**
+ * Hook for programmatic navigation with more options
+ * Provides direct access to Next.js router methods with RouteConfigContext support
+ *
+ * NOTE: Does not include searchParams to avoid Suspense.
+ * Use useSearchParams() directly in components that need it.
+ */
+export function useAppNavigation() {
+  const router = useRouter();
+  const pathname = usePathname();
+  const params = useParams();
+  const { resolvePath } = useRouteConfig();
+
+  // Wrap router.push and router.replace with path resolution
+  const push = useCallback(
+    (href: string, options?: { scroll?: boolean }) => {
+      const [pathPart, queryPart] = href.split("?");
+      const resolvedPath = resolvePath(pathPart);
+      const fullPath = queryPart ? `${resolvedPath}?${queryPart}` : resolvedPath;
+      router.push(fullPath, options);
+    },
+    [router, resolvePath],
+  );
+
+  const replace = useCallback(
+    (href: string, options?: { scroll?: boolean }) => {
+      const [pathPart, queryPart] = href.split("?");
+      const resolvedPath = resolvePath(pathPart);
+      const fullPath = queryPart ? `${resolvedPath}?${queryPart}` : resolvedPath;
+      router.replace(fullPath, options);
+    },
+    [router, resolvePath],
+  );
+
+  return {
+    /** Current pathname */
+    pathname,
+    /** Current route params */
+    params: params as Record<string, string>,
+    /** Navigate to a new path (with RouteConfigContext support) */
+    push,
+    /** Replace current history entry (with RouteConfigContext support) */
+    replace,
+    /** Go back in history */
+    back: router.back,
+    /** Go forward in history */
+    forward: router.forward,
+    /** Refresh the current route */
+    refresh: router.refresh,
+    /** Prefetch a route for faster navigation */
+    prefetch: router.prefetch,
+  };
+}
+
+// Re-export Next.js hooks for convenience
+export { useRouter, usePathname, useParams, useSearchParams };