Skip to content

🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.

7.1 KB
Raw Blame
/**
 * ViewPreferencesContext - Manages user display preferences persisted to localStorage.
 *
 * Purpose:
 * - Stores toggle states for tree item display (duration, cost, scores, comments)
 * - Manages minimum observation level filter
 * - Persists preferences across sessions via localStorage
 *
 * Not responsible for:
 * - Trace data - see TraceDataContext
 * - Selection/navigation state - see SelectionContext
 */

import { createContext, useContext, useMemo, type ReactNode } from "react";
import { type ObservationLevelType, ObservationLevel } from "@langfuse/shared";
import useLocalStorage from "@/src/components/useLocalStorage";
import { useCollapseSystemPromptPreference } from "@/src/hooks/useCollapsibleSystemPrompt";
import {
  GRAPH_VIEW_MODES,
  type GraphViewMode,
} from "@/src/features/trace-graph-view/types";

import {
  DEFAULT_JSON_VIEW_PREFERENCE,
  JSON_VIEW_PREFERENCE_STORAGE_KEY,
  type JsonViewPreference,
  normalizeJsonViewPreference,
} from "@/src/components/ui/jsonViewPreference";

/** Log view ordering mode */
export type LogViewMode = "chronological" | "tree-order";

/** Log view tree visualization style (only applies in tree-order mode) */
export type LogViewTreeStyle = "flat" | "indented";

/** Context in which trace is rendered - affects feature availability */
type TraceRenderContext = "fullscreen" | "peek" | "annotation";

interface ViewPreferencesContextValue {
  showDuration: boolean;
  setShowDuration: (value: boolean) => void;
  showCostTokens: boolean;
  setShowCostTokens: (value: boolean) => void;
  showScores: boolean;
  setShowScores: (value: boolean) => void;
  showComments: boolean;
  setShowComments: (value: boolean) => void;
  /** Graph panel build mode (aggregated vs expanded "as it ran") */
  graphViewMode: GraphViewMode;
  setGraphViewMode: (value: GraphViewMode) => void;
  minObservationLevel: ObservationLevelType;
  setMinObservationLevel: (value: ObservationLevelType) => void;
  /** Context in which trace is rendered (also an analytics dimension) */
  traceContext: TraceRenderContext;
  /** Whether trace is rendered in peek mode (e.g., table peek views) */
  isPeekMode: boolean;
  /** Whether trace is rendered in annotation mode (annotation queue processing) */
  isAnnotationMode: boolean;
  /** Log view ordering mode (chronological or tree-order) */
  logViewMode: LogViewMode;
  setLogViewMode: (value: LogViewMode) => void;
  /** Log view tree style (flat or indented, only applies in tree-order mode) */
  logViewTreeStyle: LogViewTreeStyle;
  setLogViewTreeStyle: (value: LogViewTreeStyle) => void;
  /** JSON view preference (pretty/formatted or raw JSON) */
  jsonViewPreference: JsonViewPreference;
  setJsonViewPreference: (value: JsonViewPreference) => void;
  /** Whether JSON Beta (advanced viewer) is enabled */
  jsonBetaEnabled: boolean;
  setJsonBetaEnabled: (value: boolean) => void;
  /** Whether long system prompts render with their section collapsed */
  collapseSystemPrompt: boolean;
  setCollapseSystemPrompt: (value: boolean) => void;
}

const ViewPreferencesContext =
  createContext<ViewPreferencesContextValue | null>(null);

export function useViewPreferences(): ViewPreferencesContextValue {
  const context = useContext(ViewPreferencesContext);
  if (!context) {
    throw new Error(
      "useViewPreferences must be used within a ViewPreferencesProvider",
    );
  }
  return context;
}

interface ViewPreferencesProviderProps {
  children: ReactNode;
  /** Context in which trace is rendered - affects feature availability */
  traceContext?: TraceRenderContext;
}

export function ViewPreferencesProvider({
  children,
  traceContext = "fullscreen",
}: ViewPreferencesProviderProps) {
  const isPeekMode = traceContext === "peek";
  const isAnnotationMode = traceContext === "annotation";
  const [showDuration, setShowDuration] = useLocalStorage(
    "durationOnObservationTree",
    true,
  );
  const [showCostTokens, setShowCostTokens] = useLocalStorage(
    "costTokensOnObservationTree",
    true,
  );
  const [showScores, setShowScores] = useLocalStorage(
    "scoresOnObservationTree",
    true,
  );
  const [showComments, setShowComments] = useLocalStorage("showComments", true);
  const [storedGraphViewMode, setGraphViewMode] =
    useLocalStorage<GraphViewMode>("graphViewMode", "aggregated");
  // Sanitize persisted values: the mode enum may evolve and a stale
  // localStorage entry must degrade to the default, not break the graph.
  const graphViewMode = GRAPH_VIEW_MODES.includes(storedGraphViewMode)
    ? storedGraphViewMode
    : "aggregated";
  const [minObservationLevel, setMinObservationLevel] =
    useLocalStorage<ObservationLevelType>(
      "minObservationLevel",
      ObservationLevel.DEFAULT,
    );
  const [logViewMode, setLogViewMode] = useLocalStorage<LogViewMode>(
    "logViewMode",
    "chronological",
  );
  const [logViewTreeStyle, setLogViewTreeStyle] =
    useLocalStorage<LogViewTreeStyle>("logViewTreeStyle", "flat");
  const [storedJsonViewPreference, setJsonViewPreference] =
    useLocalStorage<JsonViewPreference>(
      JSON_VIEW_PREFERENCE_STORAGE_KEY,
      DEFAULT_JSON_VIEW_PREFERENCE,
    );
  const jsonViewPreference = normalizeJsonViewPreference(
    storedJsonViewPreference,
  );
  // Migration: default to true if user had json-beta selected previously
  // TODO: Remove migration logic after 2025-01-26 (2 weeks) when user settings are migrated
  const [jsonBetaEnabled, setJsonBetaEnabled] = useLocalStorage<boolean>(
    "jsonBetaEnabled",
    typeof window !== "undefined" &&
      localStorage.getItem(JSON_VIEW_PREFERENCE_STORAGE_KEY) === '"json-beta"',
  );
  // Shared with the section caret on system prompt messages;
  // instances sync via useLocalStorage's localStorageChange events.
  const [collapseSystemPrompt, setCollapseSystemPrompt] =
    useCollapseSystemPromptPreference();

  const value = useMemo<ViewPreferencesContextValue>(
    () => ({
      showDuration,
      setShowDuration,
      showCostTokens,
      setShowCostTokens,
      showScores,
      setShowScores,
      showComments,
      setShowComments,
      graphViewMode,
      setGraphViewMode,
      minObservationLevel,
      setMinObservationLevel,
      traceContext,
      isPeekMode,
      isAnnotationMode,
      logViewMode,
      setLogViewMode,
      logViewTreeStyle,
      setLogViewTreeStyle,
      jsonViewPreference,
      setJsonViewPreference,
      jsonBetaEnabled,
      setJsonBetaEnabled,
      collapseSystemPrompt,
      setCollapseSystemPrompt,
    }),
    [
      showDuration,
      setShowDuration,
      showCostTokens,
      setShowCostTokens,
      showScores,
      setShowScores,
      showComments,
      setShowComments,
      graphViewMode,
      setGraphViewMode,
      minObservationLevel,
      setMinObservationLevel,
      traceContext,
      isPeekMode,
      isAnnotationMode,
      logViewMode,
      setLogViewMode,
      logViewTreeStyle,
      setLogViewTreeStyle,
      jsonViewPreference,
      setJsonViewPreference,
      jsonBetaEnabled,
      setJsonBetaEnabled,
      collapseSystemPrompt,
      setCollapseSystemPrompt,
    ],
  );

  return (
    <ViewPreferencesContext.Provider value={value}>
      {children}
    </ViewPreferencesContext.Provider>
  );
}