Skip to content

πŸͺ’ Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.

17.2 KB
Raw Blame

Peek View Table State Management

This document describes how table state (filters, sorting, pagination, search) is managed and persisted in peek views when navigating between items using K/J keyboard shortcuts.

Overview

Peek views allow users to quickly preview table items in a side panel. When navigating between items using K/J shortcuts, tables inside the peek view remount, which would normally reset their state. The peek state management system prevents this by storing table state in a context that persists across navigation.

Panel shell, resize, and expand

TablePeekView (../peek.tsx) is responsive and keeps the peek on top of the table (it does not split the layout):

  • Desktop β€” a docked-right, non-modal Radix dialog (no overlay), so the table behind stays interactive. A left-edge handle resizes it; dragging to the far edge (or the header Expand button) expands it to the max width (viewport βˆ’ sidebar; the sidebar stays visible).
  • Handheld (useIsHandheld β€” narrower than md, or a coarse pointer on a short screen, i.e. a phone in landscape) β€” a vaul bottom drawer with native swipe-down dismissal (Expand is hidden). Not width-only: a landscape phone is wider than md and would otherwise get the desktop sheet. An inner non-modal Radix root keeps child menus and dialogs accessible: Vaul's modal option controls its gestures and backdrop but is not forwarded to its Radix root.

Dismissal:

  • Click-outside closes, with exceptions: a target inside the peek ([data-peek-content]) never closes it; clicking another table row ([data-row-index]) switches the peeked item in place; and selection checkboxes / data-ignore-outside-interaction regions / toast-layer overlays ([data-layer="toast"], e.g. the version-update banner) / the table's ignoredSelectors don't close it. Nested Radix popovers/menus opened inside the peek don't close it (DismissableLayer stacking).
  • Escape, the close button, and (mobile) swipe-down also close.

Panel state follows the local-feature-state pattern from frontend-large-feature-architecture:

  • store/peekPanelStore.ts β€” a per-mount vanilla Zustand store (lazy useState) owning ONLY the widget width + transient drag state, mutated through named actions. Selectors (selectWidgetWidth, selectIsResizing, selectDraftExpanded) return primitives so subscriptions bail out cheaply.
  • actions/resizePeekPanel.ts β€” the drag workflow (window pointer listeners β†’ store actions; on pointer-up commits a widget width or flips the expanded flag). Takes the store instance, not hooks.
  • usePeekPanelState.ts β€” the integration boundary: owns the store, derives the final width (widget vs expanded β€” measuring the sidebar offset for the expanded case), and wires drag/keyboard to the store + action. Takes isExpanded in / onExpandedChange out (the URL owns expanded).

State altitudes:

State Altitude Where it lives
expanded route (shareable, reloadable) URL peekView=expanded, managed in peek.tsx (router.replace), cleared on close by usePeekNavigation
width cross-view persisted preference store widthFraction, mirrored to localStorage (peekViewWidthFraction)
resize drag high-frequency transient store draftFraction / draftExpanded / isResizing, committed on pointer-up
which item route the peek URL param (see below)

The default width (no saved preference) is viewport-aware: 50vw, but capped in px (PEEK_MAX_DEFAULT_WIDTH_PX) so a bigger screen doesn't mean a proportionally bigger peek (LFE-10601). Normal laptops still open at 50vw; only very wide monitors trim the fraction so the peek stays comfortable and the list navigable.

The inner tree ↔ info split inside the peek is a separate react-resizable-panels group (TraceLayoutDesktop), unified with the width to persist in localStorage under a peek-scoped group id (trace-layout-peek-*) rather than per-tab sessionStorage. Its default is computed as an explicit percentage from the width the peek opens at: the info panel gets a comfortable target and the tree/timeline takes the remainder, clamped to a comfortable band β€” so extra width on a big peek flows to info (the content), not the tree (the index). A percentage (not a px defaultSize, which the library resolves against a transient mid-open width) keeps that default deterministic. The full-page trace view keeps its own share-based, per-tab layout.

The peek and the standalone trace page already share one beta-aware fetch (../../trace/useTraceDetailData.ts), one body (../../trace/TraceDetailBody.tsx β†’ TraceDetailBody), and one action set (../../trace/TraceDetailActions.tsx β€” star / publish / delete) β€” usePeekData is now a thin wrapper over the shared hook. Next slice: collapse the <Trace context> branching and fold these primitives into a single TraceDetailSurface wrapper so the peek and TracePage share one component, not four β€” see the PR discussion.

Architecture

The peek state architecture separates the persisting context provider from the remounting content:

β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚ TablePeekView (peek.tsx)                                    β”‚
β”‚                                                             β”‚
β”‚  <PeekTableStateProvider>  ← Persists across itemId changesβ”‚
β”‚    <div key={itemId}>      ← Only this remounts            β”‚
β”‚      {children}            ← Tables remount here           β”‚
β”‚    </div>                                                   β”‚
β”‚  </PeekTableStateProvider>                                  β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                            β”‚
                            β–Ό
        β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
        β”‚ Table Components (e.g., ScoresTable)  β”‚
        β”‚                                       β”‚
        β”‚  Hooks automatically detect peek:     β”‚
        β”‚  β€’ useOrderByState()                  β”‚
        β”‚  β€’ usePaginationState()               β”‚
        β”‚  β€’ useFullTextSearch()                β”‚
        β”‚                                       β”‚
        β”‚  Hooks requiring explicit wiring:     β”‚
        β”‚  β€’ useSidebarFilterState()            β”‚
        β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                            β”‚
                            β–Ό
        β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
        β”‚ Hook reads from peek context:          β”‚
        β”‚                                        β”‚
        β”‚ const peekContext = usePeekTableState()β”‚
        β”‚ if (peekContext) {                     β”‚
        β”‚   useSidebarFilterState({             β”‚
        β”‚     stateLocation: "peekContext",     β”‚
        β”‚     context: peekContext,             β”‚
        β”‚   })                                  β”‚
        β”‚   return peekContext.tableState.X      β”‚
        β”‚ }                                      β”‚
        β”‚ return urlState                        β”‚
        β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

Key Components

PeekTableStateProvider

Location: contexts/PeekTableStateProvider.tsx

  • Provides persistent state storage across peek item navigation
  • Stores filters, sorting, pagination, and search state
  • Does NOT remount when itemId changes during K/J navigation
  • Tables inside the peek view can read from this context when the relevant hook supports it or the caller explicitly wires it

Peek-Aware Hooks

Most state management hooks automatically detect when they're running inside a peek view and read/write state accordingly. useSidebarFilterState is the exception and must be wired explicitly by the caller.

  1. useSidebarFilterState - Manages filter state

    • Location: web/src/features/filters/hooks/useSidebarFilterState.tsx
    • Requires explicit hookOptions wiring: stateLocation: "peekContext" with context: usePeekTableState()
    • Without that wiring, it uses URL or session storage state instead of the peek context
  2. useOrderByState - Manages sorting state

    • Location: web/src/features/orderBy/hooks/useOrderByState.ts
    • Returns peek context state or URL state based on context availability
  3. usePaginationState - Manages pagination state

    • Location: web/src/hooks/usePaginationState.ts
    • Supports both page/limit and pageIndex/pageSize formats
    • Automatically detects peek context and uses it if available
  4. useFullTextSearch - Manages search query state

    • Location: web/src/features/search-bar/hooks/useFullTextSearch.ts
    • Handles both search query and search type state

Behavior

βœ… Expected Behavior (Fully Integrated Tables)

When using K/J navigation in peek view for fully integrated tables:

  1. User applies filter/sort/pagination/search
  2. State is stored in PeekTableStateContext
  3. User presses K/J β†’ itemId changes β†’ peek content remounts
  4. PeekTableStateProvider does NOT remount
  5. Remounted table hooks read from the same context instance
  6. Table automatically restores previous state

Fully Integrated Tables:

  • Traces table
  • Observations table
  • Scores table
  • Evaluators table
  • Events table
  • Eval Templates table (search now peek-aware)

πŸ”„ Future-Proofed Tables (Peek-Aware Hooks Added)

These tables don't currently have peek views but now use peek-aware hooks, making them ready if peek views are added:

  • Sessions table
  • Models table
  • Score Configs table

Table State Interface

The PeekTableState interface defines what state is persisted:

interface PeekTableState {
  filters: FilterState;
  sorting: OrderByState | undefined;
  pagination: { pageIndex: number; pageSize: number };
  search: { query: string | null; type: string[] };
}

An undefined sorting value means the table uses the default passed to useOrderByState. Once the user changes or disables sorting, that explicit peek-local value is persisted.

Implementation Guide

Adding Peek Views to a New Table

To make a table work with peek state persistence:

  1. Use peek-aware hooks instead of direct URL state management:

    // ❌ Don't use useQueryParams directly
    const [paginationState, setPaginationState] = useQueryParams({
      pageIndex: withDefault(NumberParam, 0),
      pageSize: withDefault(NumberParam, 50),
    });
    
    // βœ… Use usePaginationState (automatically peek-aware)
    const [paginationState, setPaginationState] = usePaginationState(0, 50);
    
  2. For search, use useFullTextSearch:

    // ❌ Don't use useQueryParam directly
    const [searchQuery, setSearchQuery] = useQueryParam("search", StringParam);
    
    // βœ… Use useFullTextSearch (automatically peek-aware)
    const { searchQuery, setSearchQuery } = useFullTextSearch();
    
  3. For filters, use useSidebarFilterState:

    const peekContext = usePeekTableState();
    
    const queryFilterOptions: UseSidebarFilterStateOptions = useMemo(() => {
      if (peekContext) {
        return {
          loading: isSidebarFilterLoading,
          implicitDefaultConfig: DEFAULT_SIDEBAR_IMPLICIT_ENVIRONMENT_CONFIG,
          stateLocation: "peekContext",
          context: peekContext,
        };
      }
    
      return {
        loading: isSidebarFilterLoading,
        implicitDefaultConfig: DEFAULT_SIDEBAR_IMPLICIT_ENVIRONMENT_CONFIG,
        stateLocation: "urlAndSessionStorage",
        sessionFilterContextId: projectId,
      };
    }, [isSidebarFilterLoading, peekContext, projectId]);
    
    const queryFilter = useSidebarFilterState(
      filterConfig,
      filterOptions,
      queryFilterOptions,
    );
    

    useSidebarFilterState no longer detects peek context internally. If the table can render inside PeekTableStateProvider, the caller must pass stateLocation: "peekContext" explicitly or filters will persist in URL or session state instead of the in-memory peek state.

  4. For sorting, use useOrderByState:

    // Already peek-aware, no changes needed if already using this hook
    const [orderByState, setOrderByState] = useOrderByState({
      column: "createdAt",
      order: "DESC",
    });
    

How It Works Internally

Most peek-aware hooks follow this pattern internally:

export const useSomeState = () => {
  const peekContext = usePeekTableState();

  // URL-based state (fallback)
  const [urlState, setUrlState] = useQueryParam(...);

  if (peekContext) {
    // In peek view: read/write from context
    const value = peekContext.tableState.someProperty;
    const setValue = (newValue) => {
      peekContext.setTableState({
        ...peekContext.tableState,
        someProperty: newValue,
      });
    };
    return { value, setValue };
  }

  // Not in peek view: use URL state
  return { value: urlState, setValue: setUrlState };
};

State Lifecycle and Caveats

When State Persists (Intended βœ“)

Table state persists during K/J keyboard navigation within the same peek view:

1. Open trace T1 β†’ apply filter to ScoresTable
2. Press K/J β†’ navigate to trace T2
3. ScoresTable in T2 retains the filter βœ“

Reason: PeekTableStateProvider remains mounted during K/J navigation. Only the content with key={itemId} remounts, preserving user's filter/sort/pagination preferences across items of the same type.

When State Resets (Safe βœ“)

Table state resets when the peek view closes:

1. Open trace T1 β†’ apply filter
2. Close peek (X button/Escape/click outside)
3. Open observation O1 β†’ fresh state βœ“

Reason: Closing the peek removes the peek URL parameter. This causes the <Sheet> component to close and unmount <SheetContent>, which unmounts PeekTableStateProvider and destroys all state.

Known Risk: Multiple Tables in One Peek View

Risk Level: LOW (theoretical edge case)

Issue: All tables in the same peek view share a single PeekTableState object. If a peek view contains multiple independent paginated tables, they share pagination/filter/sort state.

Example:

Hypothetical: Trace peek with both Scores table AND Events table
β†’ Navigate to page 2 of Scores table
β†’ context.pagination = { pageIndex: 1, pageSize: 50 }
β†’ Events table also shows page 2 ❌

Current Reality:

  • Peek views typically contain one primary table (e.g., ScoresTable in trace details)
  • Multiple instances of the same table type (e.g., trace-level scores + observation-level scores) intentionally share state
  • Tables use disableUrlPersistence and scope data via props (traceId, observationId)

Future Solution (if multiple independent table types are needed): Any follow-up design for namespaced peek state still needs to keep the explicit useSidebarFilterState wiring pattern:

const queryFilterOptions: UseSidebarFilterStateOptions = peekContext
  ? {
      loading,
      stateLocation: "peekContext",
      context: peekContext,
    }
  : {
      loading,
      stateLocation: "urlAndSessionStorage",
      sessionFilterContextId: projectId,
    };

const filters = useSidebarFilterState(config, options, queryFilterOptions);

Related Files

Content may request a temporary review width with data-peek-layout="review" (two columns) or "review-navigation" (three columns). The shell's CSS minimum width is capped at the sidebar edge; it does not write the stored widget width or expanded URL state. Nested content owns its responsive fallback when the available width is smaller than its preferred columns.