@datarecce/ui 0.1.29 → 0.1.31

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

@@ -0,0 +1,200 @@
+/**
+ * useAppRouter - Navigation utilities for Next.js App Router
+ *
+ * Provides a similar API to Wouter's useLocation for easier migration.
+ * This hook combines Next.js's useRouter, usePathname, useParams,
+ * and useSearchParams into a unified interface.
+ *
+ * IMPORTANT: useSearchParams() triggers Suspense boundaries in Next.js.
+ * To avoid full-page loading states, useAppLocation() only returns the
+ * pathname by default. Use useAppLocationWithSearch() if you need
+ * search params included in the location string.
+ */
+
+"use client";
+
+import {
+  useParams,
+  usePathname,
+  useRouter,
+  useSearchParams,
+} from "next/navigation";
+import { useCallback, useMemo } from "react";
+
+interface NavigateOptions {
+  replace?: boolean;
+  scroll?: boolean;
+}
+
+/**
+ * Hook that provides Wouter-compatible location API using Next.js App Router
+ *
+ * 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"); // Navigate to new path with query
+ * setLocation("/checks", { replace: true }); // Replace current history entry
+ */
+export function useAppLocation(): [
+  string,
+  (to: string, options?: NavigateOptions) => void,
+] {
+  const router = useRouter();
+  const pathname = usePathname();
+
+  // Navigation function compatible with Wouter's setLocation
+  const setLocation = useCallback(
+    (to: string, options?: NavigateOptions) => {
+      if (options?.replace) {
+        router.replace(to, { scroll: options?.scroll ?? true });
+      } else {
+        router.push(to, { scroll: options?.scroll ?? true });
+      }
+    },
+    [router],
+  );
+
+  return [pathname, setLocation];
+}
+
+/**
+ * Hook that includes search params in the location string.
+ *
+ * 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();
+
+  // Construct full location string including search params
+  const location = useMemo(() => {
+    const search = searchParams?.toString();
+    return search ? `${pathname}?${search}` : pathname;
+  }, [pathname, searchParams]);
+
+  // Navigation function compatible with Wouter's setLocation
+  const setLocation = useCallback(
+    (to: string, options?: NavigateOptions) => {
+      if (options?.replace) {
+        router.replace(to, { scroll: options?.scroll ?? true });
+      } else {
+        router.push(to, { scroll: options?.scroll ?? true });
+      }
+    },
+    [router],
+  );
+
+  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
+ *
+ * @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
+ *
+ * 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();
+
+  return {
+    /** Current pathname */
+    pathname,
+    /** Current route params */
+    params: params as Record<string, string>,
+    /** Navigate to a new path */
+    push: router.push,
+    /** Replace current history entry */
+    replace: router.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 };

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

@@ -0,0 +1,99 @@
+/**
+ * Custom hook for managing check events (timeline/conversation).
+ *
+ * Provides data fetching with polling for real-time updates,
+ * and mutation functions for CRUD operations.
+ */
+
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { cacheKeys } from "@/lib/api/cacheKeys";
+import {
+  CheckEvent,
+  createComment,
+  deleteComment,
+  listCheckEvents,
+  updateComment,
+} from "@/lib/api/checkEvents";
+import { useApiConfig } from "./ApiConfigContext";
+
+const POLLING_INTERVAL = 10000; // 10 seconds
+
+interface UseCheckEventsOptions {
+  enabled?: boolean;
+}
+
+export function useCheckEvents(
+  checkId: string,
+  options: UseCheckEventsOptions = {},
+) {
+  const { enabled = true } = options;
+  const queryClient = useQueryClient();
+  const { apiClient } = useApiConfig();
+
+  // Fetch events with polling
+  const {
+    data: events,
+    isLoading,
+    error,
+    refetch,
+  } = useQuery({
+    queryKey: cacheKeys.checkEvents(checkId),
+    queryFn: () => listCheckEvents(checkId, apiClient),
+    enabled,
+    refetchInterval: POLLING_INTERVAL,
+    refetchIntervalInBackground: false,
+  });
+
+  // Create comment mutation
+  const createCommentMutation = useMutation({
+    mutationFn: (content: string) => createComment(checkId, content, apiClient),
+    onSuccess: async () => {
+      await queryClient.invalidateQueries({
+        queryKey: cacheKeys.checkEvents(checkId),
+      });
+    },
+  });
+
+  // Update comment mutation
+  const updateCommentMutation = useMutation({
+    mutationFn: ({ eventId, content }: { eventId: string; content: string }) =>
+      updateComment(checkId, eventId, content, apiClient),
+    onSuccess: async () => {
+      await queryClient.invalidateQueries({
+        queryKey: cacheKeys.checkEvents(checkId),
+      });
+    },
+  });
+
+  // Delete comment mutation
+  const deleteCommentMutation = useMutation({
+    mutationFn: (eventId: string) => deleteComment(checkId, eventId, apiClient),
+    onSuccess: async () => {
+      await queryClient.invalidateQueries({
+        queryKey: cacheKeys.checkEvents(checkId),
+      });
+    },
+  });
+
+  return {
+    events: events ?? [],
+    isLoading,
+    error,
+    refetch,
+
+    // Mutations
+    createComment: createCommentMutation.mutate,
+    isCreatingComment: createCommentMutation.isPending,
+    createCommentError: createCommentMutation.error,
+
+    // Use mutateAsync for updateComment to allow awaiting in UI
+    updateComment: updateCommentMutation.mutateAsync,
+    isUpdatingComment: updateCommentMutation.isPending,
+    updateCommentError: updateCommentMutation.error,
+
+    // Use mutateAsync for deleteComment to allow awaiting in UI
+    deleteComment: deleteCommentMutation.mutateAsync,
+    isDeletingComment: deleteCommentMutation.isPending,
+    deleteCommentError: deleteCommentMutation.error,
+  };
+}

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

@@ -0,0 +1,14 @@
+import { toaster } from "@/components/ui/toaster";
+
+export function useCheckToast() {
+  function markedAsApprovedToast() {
+    toaster.create({
+      title: "Marked as approved",
+      type: "success",
+      duration: 2000,
+    });
+  }
+  return {
+    markedAsApprovedToast,
+  };
+}

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

@@ -0,0 +1,27 @@
+import { toaster } from "@/components/ui/toaster";
+
+export function useClipBoardToast() {
+  function successToast(message: string) {
+    toaster.create({
+      description: message,
+      type: "info",
+      duration: 5000,
+      closable: true,
+    });
+  }
+
+  function failToast(title: string, error: unknown) {
+    toaster.create({
+      title: title,
+      description: String(error),
+      type: "error",
+      duration: 5000,
+      closable: true,
+    });
+  }
+
+  return {
+    successToast,
+    failToast,
+  };
+}

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

@@ -0,0 +1,102 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import { useTimeout } from "usehooks-ts";
+import { toaster } from "@/components/ui/toaster";
+
+const COUNTDOWN_CONFIG = {
+  TOAST_ID: "lifetime-countdown",
+  WARNING_THRESHOLD: 60, // seconds before expiry to show warning
+  UPDATE_INTERVAL: 1000, // milliseconds
+  MESSAGE: (seconds: number) =>
+    `The server will be closed in ${seconds} seconds.`,
+  STYLE: {
+    fontFamily: "monospace",
+  },
+} as const;
+
+/**
+ * Hook to manage countdown toast notifications for server lifetime
+ * @param lifetimeExpiredAt - Date when the server will expire
+ */
+export function useCountdownToast(lifetimeExpiredAt: Date | undefined) {
+  const countdownToast = toaster;
+  const [countdownToastId, setCountdownToastId] = useState<string | null>(null);
+  const countdownIntervalRef = useRef<NodeJS.Timeout>(undefined);
+
+  const calculateRemainingSeconds = useCallback(() => {
+    if (!lifetimeExpiredAt) return 0;
+
+    const now = new Date();
+    const remaining = Math.floor(
+      (lifetimeExpiredAt.getTime() - now.getTime()) / 1000,
+    );
+    return Math.max(0, remaining); // Ensure we don't return negative values
+  }, [lifetimeExpiredAt]);
+
+  const cleanupToast = useCallback(() => {
+    if (countdownToastId != null) {
+      countdownToast.remove(countdownToastId);
+      setCountdownToastId(null);
+    }
+  }, [countdownToast, countdownToastId]);
+
+  const updateToast = useCallback(() => {
+    if (countdownToastId == null) return;
+
+    const remainingSeconds = calculateRemainingSeconds();
+    if (remainingSeconds <= 0) {
+      cleanupToast();
+      return;
+    }
+
+    countdownToast.update(countdownToastId, {
+      description: COUNTDOWN_CONFIG.MESSAGE(remainingSeconds),
+    });
+  }, [
+    countdownToastId,
+    calculateRemainingSeconds,
+    countdownToast,
+    cleanupToast,
+  ]);
+
+  const showToast = useCallback(() => {
+    if (!lifetimeExpiredAt) return;
+
+    // Cleanup any existing toast before showing new one
+    cleanupToast();
+
+    const remainingSeconds = calculateRemainingSeconds();
+    if (remainingSeconds <= 0) return;
+
+    setCountdownToastId(
+      countdownToast.create({
+        id: COUNTDOWN_CONFIG.TOAST_ID,
+        description: COUNTDOWN_CONFIG.MESSAGE(remainingSeconds),
+      }),
+    );
+
+    countdownIntervalRef.current = setInterval(
+      updateToast,
+      COUNTDOWN_CONFIG.UPDATE_INTERVAL,
+    );
+  }, [
+    lifetimeExpiredAt,
+    countdownToast,
+    calculateRemainingSeconds,
+    updateToast,
+    cleanupToast,
+  ]);
+
+  // Calculate delay for showing toast
+  const remainingSeconds = calculateRemainingSeconds();
+  const delay = lifetimeExpiredAt
+    ? Math.max(0, remainingSeconds - COUNTDOWN_CONFIG.WARNING_THRESHOLD) * 1000
+    : null;
+
+  // Use useTimeout hook to schedule toast display
+  useTimeout(showToast, delay);
+
+  // Cleanup effect
+  useEffect(() => {
+    return cleanupToast;
+  }, [cleanupToast]);
+}

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

@@ -0,0 +1,130 @@
+import Box from "@mui/material/Box";
+import IconButton from "@mui/material/IconButton";
+import Link from "@mui/material/Link";
+import Stack from "@mui/material/Stack";
+import { useState } from "react";
+import { LuExternalLink } from "react-icons/lu";
+import { toaster } from "@/components/ui/toaster";
+
+function ReactionFeedback({
+  description,
+  onLike,
+  onDislike,
+  onClickLink,
+  externalLink,
+  externalLinkText,
+}: {
+  description: string;
+  onLike: () => void;
+  onDislike: () => void;
+  onClickLink: () => void;
+  externalLink?: string;
+  externalLinkText?: string;
+}) {
+  return (
+    <Box
+      sx={{
+        display: "flex",
+        gap: 4,
+        justifyContent: "center",
+        alignContent: "center",
+        alignItems: "center",
+      }}
+    >
+      {description}
+      <IconButton
+        aria-label="thumbs up"
+        onClick={onLike}
+        sx={{ width: "32px", height: "32px" }}
+      >
+        <Box component="img" src="/imgs/feedback/thumbs-up.png" alt="like" />
+      </IconButton>
+      <IconButton
+        aria-label="thumbs down"
+        onClick={onDislike}
+        sx={{ width: "32px", height: "32px" }}
+      >
+        <Box
+          component="img"
+          src="/imgs/feedback/thumbs-down.png"
+          alt="dislike"
+        />
+      </IconButton>
+      {externalLink && externalLinkText && (
+        <Link
+          href={externalLink}
+          target="_blank"
+          onClick={onClickLink}
+          sx={{ textDecoration: "underline" }}
+        >
+          {externalLinkText} <LuExternalLink />
+        </Link>
+      )}
+    </Box>
+  );
+}
+
+export function useFeedbackCollectionToast(options: {
+  feedbackId: string;
+  description: string;
+  onFeedbackSubmit: (feedback: string) => void;
+  externalLink?: string;
+  externalLinkText?: string;
+}) {
+  const {
+    feedbackId,
+    description,
+    onFeedbackSubmit,
+    externalLink,
+    externalLinkText,
+  } = options;
+  const [toastId, setToastId] = useState<string | undefined>(undefined);
+
+  function feedBackCollectionToast(skipBypassFeedback = false) {
+    const isSkipFeedback = localStorage.getItem(feedbackId);
+    if (toastId != null) {
+      // Don't show the toast again if it's already active
+      return;
+    }
+    if (isSkipFeedback === "true" && !skipBypassFeedback) {
+      return;
+    }
+
+    setToastId(
+      toaster.create({
+        id: feedbackId,
+        duration: undefined,
+        type: "success",
+        description: (
+          <Stack direction="row">
+            <ReactionFeedback
+              description={description}
+              onLike={() => {
+                onFeedbackSubmit("like");
+                toaster.dismiss(feedbackId);
+                localStorage.setItem(feedbackId, "true");
+              }}
+              onDislike={() => {
+                onFeedbackSubmit("dislike");
+                toaster.dismiss(feedbackId);
+                localStorage.setItem(feedbackId, "true");
+              }}
+              externalLink={externalLink}
+              externalLinkText={externalLinkText}
+              onClickLink={() => {
+                onFeedbackSubmit("link");
+              }}
+            />
+          </Stack>
+        ),
+      }),
+    );
+  }
+
+  return {
+    feedbackToast: feedBackCollectionToast,
+    closeToast: () => {
+      if (toastId) toaster.dismiss(toastId);
+    },
+  };
+}

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

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