πͺ’ Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.
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 thanmd, or a coarse pointer on a short screen, i.e. a phone in landscape) β avaulbottom drawer with native swipe-down dismissal (Expand is hidden). Not width-only: a landscape phone is wider thanmdand would otherwise get the desktop sheet. An inner non-modal Radix root keeps child menus and dialogs accessible: Vaul'smodaloption 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-interactionregions / toast-layer overlays ([data-layer="toast"], e.g. the version-update banner) / the table'signoredSelectorsdon'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 (lazyuseState) owning ONLY the widget width + transient drag state, mutated through namedactions. 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. TakesisExpandedin /onExpandedChangeout (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
itemIdchanges 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.
useSidebarFilterState- Manages filter state- Location:
web/src/features/filters/hooks/useSidebarFilterState.tsx - Requires explicit
hookOptionswiring:stateLocation: "peekContext"withcontext: usePeekTableState() - Without that wiring, it uses URL or session storage state instead of the peek context
- Location:
useOrderByState- Manages sorting state- Location:
web/src/features/orderBy/hooks/useOrderByState.ts - Returns peek context state or URL state based on context availability
- Location:
usePaginationState- Manages pagination state- Location:
web/src/hooks/usePaginationState.ts - Supports both
page/limitandpageIndex/pageSizeformats - Automatically detects peek context and uses it if available
- Location:
useFullTextSearch- Manages search query state- Location:
web/src/features/search-bar/hooks/useFullTextSearch.ts - Handles both search query and search type state
- Location:
Behavior
β Expected Behavior (Fully Integrated Tables)
When using K/J navigation in peek view for fully integrated tables:
- User applies filter/sort/pagination/search
- State is stored in
PeekTableStateContext - User presses K/J β
itemIdchanges β peek content remounts PeekTableStateProviderdoes NOT remount- Remounted table hooks read from the same context instance
- 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:
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);For search, use useFullTextSearch:
// β Don't use useQueryParam directly const [searchQuery, setSearchQuery] = useQueryParam("search", StringParam); // β Use useFullTextSearch (automatically peek-aware) const { searchQuery, setSearchQuery } = useFullTextSearch();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, );useSidebarFilterStateno longer detects peek context internally. If the table can render insidePeekTableStateProvider, the caller must passstateLocation: "peekContext"explicitly or filters will persist in URL or session state instead of the in-memory peek state.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
disableUrlPersistenceand 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
- Peek state context:
contexts/PeekTableStateProvider.tsx - Pagination hook:
web/src/hooks/usePaginationState.ts - Full text search hook:
search-bar/hooks/useFullTextSearch.ts - Filter state hook:
web/src/features/filters/hooks/useSidebarFilterState.tsx - Order by hook:
web/src/features/orderBy/hooks/useOrderByState.ts
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.