@agentmark-ai/ui-components 0.1.0 → 0.3.0

package/dist/index.d.mts

@@ -1,7 +1,7 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { GridFilterModel, GridSortModel, DataGridProps } from '@mui/x-data-grid';
 import * as React$1 from 'react';
-import React__default, { ReactNode, ComponentProps } from 'react';
+import React__default, { ReactNode, Component, ComponentProps } from 'react';
 import { SxProps, Theme } from '@mui/material/styles';
 import { Node, Edge } from '@xyflow/react';
 import { UseTreeItemParameters } from '@mui/x-tree-view/useTreeItem';
@@ -490,6 +490,385 @@ interface TraceGraphCanvasProps {
 }
 declare function TraceGraphCanvas({ graphData, isLoading, }: TraceGraphCanvasProps): react_jsx_runtime.JSX.Element;
 
+/**
+ * Timeline Types for Trace Timeline View
+ *
+ * TypeScript interfaces for timeline-specific computed values.
+ * Operates on existing SpanData with no data model changes.
+ */
+
+/**
+ * Computed layout for a single span bar in the timeline.
+ */
+interface TimelineBarLayout {
+    /** Original span ID */
+    spanId: string;
+    /** Span name for display */
+    name: string;
+    /** Horizontal position (0-1 normalized) */
+    x: number;
+    /** Bar width (0-1 normalized) */
+    width: number;
+    /** Vertical row index (0-based) */
+    row: number;
+    /** Nesting depth (0 = root) */
+    depth: number;
+    /** Duration in milliseconds */
+    durationMs: number;
+    /** Start time in milliseconds (relative to trace start) */
+    startTimeMs: number;
+    /** Percentage of total trace duration */
+    percentOfTrace: number;
+    /** Node type for coloring (reuses WorkflowNodeType) */
+    nodeType: WorkflowNodeType;
+    /** Error indicator */
+    hasError: boolean;
+    /** Reference to original span */
+    span: SpanData;
+}
+/**
+ * Zoom/pan state for the timeline viewport.
+ */
+interface TimelineViewState {
+    /** SVG viewBox dimensions */
+    viewBox: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /** Current zoom scale (1 = 100%) */
+    scale: number;
+    /** Whether user is currently panning */
+    isPanning: boolean;
+}
+/**
+ * Aggregate metrics for the timeline.
+ */
+interface TimelineMetrics {
+    /** Total trace duration in milliseconds */
+    totalDurationMs: number;
+    /** Trace start time (earliest span timestamp) */
+    startTimeMs: number;
+    /** Trace end time (latest span end) */
+    endTimeMs: number;
+    /** Total number of spans */
+    spanCount: number;
+    /** Maximum nesting depth */
+    maxDepth: number;
+    /** Count of spans by type */
+    typeBreakdown: Partial<Record<WorkflowNodeType, number>>;
+}
+/**
+ * Time axis tick mark for the ruler.
+ */
+interface TimelineRulerTick {
+    /** Position on the axis (0-1 normalized) */
+    position: number;
+    /** Display label (e.g., "0ms", "500ms", "1.2s") */
+    label: string;
+    /** Whether this is a major tick (larger, with label) */
+    isMajor: boolean;
+}
+/**
+ * Layout constants for timeline rendering.
+ */
+declare const TIMELINE_CONSTANTS: {
+    /** Height of each span row in pixels */
+    readonly ROW_HEIGHT: 28;
+    /** Minimum bar width in pixels (for very short spans) */
+    readonly MIN_BAR_WIDTH: 4;
+    /** Indentation per depth level in pixels */
+    readonly DEPTH_INDENT: 16;
+    /** Bar height as ratio of row height */
+    readonly BAR_HEIGHT_RATIO: 0.7;
+    /** Minimum zoom scale */
+    readonly MIN_SCALE: 0.5;
+    /** Maximum zoom scale */
+    readonly MAX_SCALE: 10;
+    /** Height of the time ruler in pixels */
+    readonly RULER_HEIGHT: 24;
+    /** Padding around the timeline content */
+    readonly PADDING: 8;
+    /** Label area width for span names */
+    readonly LABEL_WIDTH: 120;
+};
+/**
+ * Props for the TimelineBar component.
+ */
+interface TimelineBarProps {
+    /** Computed layout for this bar */
+    layout: TimelineBarLayout;
+    /** Whether this bar is currently selected */
+    isSelected: boolean;
+    /** Whether this bar is currently focused (keyboard navigation) */
+    isFocused?: boolean;
+    /** Callback when bar is clicked */
+    onSelect?: (spanId: string) => void;
+    /** Callback when mouse enters bar */
+    onMouseEnter?: (layout: TimelineBarLayout, event: React.MouseEvent) => void;
+    /** Callback when mouse leaves bar */
+    onMouseLeave?: () => void;
+    /** Total width of the timeline area in pixels */
+    timelineWidth: number;
+}
+/**
+ * Props for the TimelineRuler component.
+ */
+interface TimelineRulerProps {
+    /** Tick marks to display */
+    ticks: TimelineRulerTick[];
+    /** Total width of the ruler in pixels */
+    width: number;
+    /** Height of the ruler in pixels */
+    height?: number;
+}
+/**
+ * Props for the TimelineTooltip component.
+ */
+interface TimelineTooltipProps {
+    /** Layout data for the hovered span */
+    layout: TimelineBarLayout | null;
+    /** Tooltip position */
+    position: {
+        x: number;
+        y: number;
+    } | null;
+    /** Whether tooltip is visible */
+    visible: boolean;
+}
+/**
+ * Props for the TimelineLegend component.
+ */
+interface TimelineLegendProps {
+    /** Type breakdown from metrics */
+    typeBreakdown: Partial<Record<WorkflowNodeType, number>>;
+    /** Whether to show counts */
+    showCounts?: boolean;
+}
+/**
+ * Props for the main TraceTimeline component.
+ */
+interface TraceTimelineProps {
+    /** Spans to visualize */
+    spans: SpanData[];
+    /** Currently selected span ID */
+    selectedSpanId?: string;
+    /** Callback when a span is selected */
+    onSelectSpan?: (spanId: string) => void;
+    /** Whether to show the time ruler */
+    showRuler?: boolean;
+    /** Whether to show the type legend */
+    showLegend?: boolean;
+    /** Whether to enable mouse wheel zoom */
+    enableZoom?: boolean;
+    /** Whether to enable drag to pan */
+    enablePan?: boolean;
+    /** Custom styles */
+    sx?: Record<string, unknown>;
+    /** Loading state */
+    isLoading?: boolean;
+}
+/**
+ * Return type for useTimelineLayout hook.
+ */
+interface UseTimelineLayoutResult {
+    /** Computed layouts for all spans */
+    layouts: TimelineBarLayout[];
+    /** Aggregate metrics */
+    metrics: TimelineMetrics;
+    /** Ruler tick marks */
+    rulerTicks: TimelineRulerTick[];
+}
+/**
+ * Return type for useTimelineZoom hook.
+ */
+interface UseTimelineZoomResult {
+    /** Current view state */
+    viewState: TimelineViewState;
+    /** Zoom in by a factor */
+    zoomIn: () => void;
+    /** Zoom out by a factor */
+    zoomOut: () => void;
+    /** Reset to fit all content */
+    resetZoom: () => void;
+    /** Set zoom to specific scale */
+    setScale: (scale: number) => void;
+    /** Handler for mouse wheel events */
+    onWheel: (event: React.WheelEvent) => void;
+    /** Handlers for pan (drag) events */
+    panHandlers: {
+        onMouseDown: (event: React.MouseEvent) => void;
+        onMouseMove: (event: React.MouseEvent) => void;
+        onMouseUp: () => void;
+        onMouseLeave: () => void;
+    };
+}
+
+/**
+ * computeTimelineLayout - Pure function for timeline layout computation
+ *
+ * Computes timeline bar layouts from span data using depth-first traversal.
+ * Handles hierarchical positioning, concurrent span detection, and time normalization.
+ *
+ * This is extracted as a pure function to enable direct unit testing without React context.
+ */
+
+/**
+ * Format duration for display.
+ * @param ms Duration in milliseconds
+ * @returns Formatted string (e.g., "500ms", "1.2s", "2m 30s")
+ */
+declare function formatDuration(ms: number): string;
+/**
+ * Compute timeline layouts from span data.
+ *
+ * @param spans Array of span data to visualize
+ * @returns Computed layouts, metrics, and ruler ticks
+ */
+declare function computeTimelineLayout(spans: SpanData[]): UseTimelineLayoutResult;
+
+/**
+ * useTimelineLayout Hook
+ *
+ * React hook wrapper around computeTimelineLayout.
+ * Provides memoization for performance optimization.
+ */
+
+/**
+ * Hook to compute timeline layouts from span data.
+ *
+ * @param spans Array of span data to visualize
+ * @returns Computed layouts, metrics, and ruler ticks
+ */
+declare function useTimelineLayout(spans: SpanData[]): UseTimelineLayoutResult;
+
+/**
+ * useTimelineZoom Hook
+ *
+ * Manages zoom and pan state for the timeline SVG viewport.
+ * Supports mouse wheel zoom, drag-to-pan, and programmatic zoom controls.
+ */
+
+/**
+ * Hook to manage timeline zoom and pan state.
+ *
+ * @param contentWidth Total width of the timeline content
+ * @param contentHeight Total height of the timeline content
+ * @returns Zoom state and control handlers
+ */
+declare function useTimelineZoom(contentWidth?: number, contentHeight?: number): UseTimelineZoomResult;
+
+/**
+ * useTimelineViewPreference Hook
+ *
+ * Manages user preference for graph vs timeline view with localStorage persistence.
+ * Used by consuming applications to implement view toggle functionality.
+ */
+/** Available trace view types */
+type TraceViewType = "graph" | "timeline";
+/**
+ * Hook to manage trace view preference with localStorage persistence.
+ *
+ * @returns Current view, setter, and toggle function
+ */
+declare function useTimelineViewPreference(): {
+    /** Current view type */
+    view: TraceViewType;
+    /** Set view to specific type */
+    setView: (newView: TraceViewType) => void;
+    /** Toggle between graph and timeline */
+    toggleView: () => void;
+    /** Whether current view is timeline */
+    isTimeline: boolean;
+    /** Whether current view is graph */
+    isGraph: boolean;
+};
+
+/**
+ * TraceTimeline Component
+ *
+ * Main container for the trace timeline visualization.
+ * Displays spans as horizontal bars positioned by start time and sized by duration.
+ */
+
+/**
+ * TraceTimeline component displays spans as a waterfall timeline.
+ */
+declare const TraceTimeline: React__default.NamedExoticComponent<TraceTimelineProps>;
+
+/**
+ * TimelineBar Component
+ *
+ * Renders a single span bar in the timeline visualization.
+ * Displays the span as a horizontal bar with appropriate positioning, sizing, and styling.
+ */
+
+/**
+ * TimelineBar component renders a single span bar.
+ */
+declare const TimelineBar: React__default.NamedExoticComponent<TimelineBarProps>;
+
+/**
+ * TimelineRuler Component
+ *
+ * Renders the time axis with tick marks and labels for the timeline.
+ */
+
+/**
+ * TimelineRuler component renders the time axis.
+ */
+declare const TimelineRuler: React__default.NamedExoticComponent<TimelineRulerProps>;
+
+/**
+ * TimelineTooltip Component
+ *
+ * Displays hover tooltip with span details for the timeline.
+ */
+
+/**
+ * TimelineTooltip component displays span details on hover.
+ */
+declare const TimelineTooltip: React__default.NamedExoticComponent<TimelineTooltipProps>;
+
+/**
+ * TimelineLegend Component
+ *
+ * Displays a legend showing span type colors for the timeline.
+ */
+
+/**
+ * TimelineLegend component displays span type colors.
+ */
+declare const TimelineLegend: React__default.NamedExoticComponent<TimelineLegendProps>;
+
+/**
+ * TimelineErrorBoundary Component
+ *
+ * Error boundary to gracefully handle rendering errors in the timeline.
+ * Prevents crashes from malformed span data from breaking the entire UI.
+ */
+
+interface TimelineErrorBoundaryProps {
+    children: ReactNode;
+    fallback?: ReactNode;
+}
+interface TimelineErrorBoundaryState {
+    hasError: boolean;
+    error: Error | null;
+}
+/**
+ * Error boundary for the timeline component.
+ * Catches rendering errors and displays a fallback UI.
+ */
+declare class TimelineErrorBoundary extends Component<TimelineErrorBoundaryProps, TimelineErrorBoundaryState> {
+    constructor(props: TimelineErrorBoundaryProps);
+    static getDerivedStateFromError(error: Error): TimelineErrorBoundaryState;
+    componentDidCatch(error: Error, errorInfo: React__default.ErrorInfo): void;
+    handleRetry: () => void;
+    render(): ReactNode;
+}
+
 interface SpanInfoContentProps {
     children: React.ReactNode;
 }
@@ -670,4 +1049,4 @@ declare function JsonEditor({ defaultValue, onChange, value, }: {
     value?: string;
 }): react_jsx_runtime.JSX.Element;
 
-export { AddAnnotationDialog, AddAnnotations, AttributesTab, AttributesViewer, DataGrid, EmptyContent, EvaluationList, EvaluationProvider, EvaluationTab, FormProvider, Iconify, InputOutputTab, JsonEditor, type LLMPrompt, type LLMText, Label, type LabelColor, type LabelProps, type LabelVariant, type LayoutResult, NODE_DIMENSIONS, type NodeGroup, type NodeTypeStyle, OutputDisplay, PromptList, RHFJsonEditor, RHFMultiSelect, RHFSelect, RHFSlider, RHFSwitch, RHFTextField, type Request, Requests, type ScoreData, type Session, type SessionData, SessionsList, type SessionsListProps, type SpanData, type SpanForGrouping, SpanInfoContent, SpanInfoHeader, SpanInfoProvider, SpanInfoTabs, SpanInfoTitle, TableEmptyRows, TableHeadCustom, TablePaginationCustom, type TableProps, TableSelectedAction, TableSkeleton, type Trace, type TraceData, TraceDrawer, TraceDrawerCloseButton, TraceDrawerContainer, TraceDrawerContent, type TraceDrawerContextValue, TraceDrawerHeader, TraceDrawerMain, TraceDrawerProvider, type TraceDrawerProviderProps, TraceDrawerSidebar, TraceDrawerSidebarSectionResizer, TraceDrawerSubtitle, TraceDrawerTitle, TraceGraphCanvas, type TraceGraphCanvasProps, TraceInfoSkeleton, TraceLabel, type TraceListContextValue, TraceListItem, TraceListProvider, TraceTree, TraceTreeItem, TracesList, type TracesListProps, type WorkflowNodeType, applyDagreLayout, calculateBranchFamilies, getBranchColor, getDisplayName, getNodeTypeStyle, groupSpansByKey, hasChildSpans, inferNodeType, makeGroupKey, useEvaluationContext, useSpanInfoContext, useTable, useTraceDrawer, useTraceDrawerContext, useTraceListContext };
+export { AddAnnotationDialog, AddAnnotations, AttributesTab, AttributesViewer, DataGrid, EmptyContent, EvaluationList, EvaluationProvider, EvaluationTab, FormProvider, Iconify, InputOutputTab, JsonEditor, type LLMPrompt, type LLMText, Label, type LabelColor, type LabelProps, type LabelVariant, type LayoutResult, NODE_DIMENSIONS, type NodeGroup, type NodeTypeStyle, OutputDisplay, PromptList, RHFJsonEditor, RHFMultiSelect, RHFSelect, RHFSlider, RHFSwitch, RHFTextField, type Request, Requests, type ScoreData, type Session, type SessionData, SessionsList, type SessionsListProps, type SpanData, type SpanForGrouping, SpanInfoContent, SpanInfoHeader, SpanInfoProvider, SpanInfoTabs, SpanInfoTitle, TIMELINE_CONSTANTS, TableEmptyRows, TableHeadCustom, TablePaginationCustom, type TableProps, TableSelectedAction, TableSkeleton, TimelineBar, type TimelineBarLayout, type TimelineBarProps, TimelineErrorBoundary, TimelineLegend, type TimelineLegendProps, type TimelineMetrics, TimelineRuler, type TimelineRulerProps, type TimelineRulerTick, TimelineTooltip, type TimelineTooltipProps, type TimelineViewState, type Trace, type TraceData, TraceDrawer, TraceDrawerCloseButton, TraceDrawerContainer, TraceDrawerContent, type TraceDrawerContextValue, TraceDrawerHeader, TraceDrawerMain, TraceDrawerProvider, type TraceDrawerProviderProps, TraceDrawerSidebar, TraceDrawerSidebarSectionResizer, TraceDrawerSubtitle, TraceDrawerTitle, TraceGraphCanvas, type TraceGraphCanvasProps, TraceInfoSkeleton, TraceLabel, type TraceListContextValue, TraceListItem, TraceListProvider, TraceTimeline, type TraceTimelineProps, TraceTree, TraceTreeItem, type TraceViewType, TracesList, type TracesListProps, type UseTimelineLayoutResult, type UseTimelineZoomResult, type WorkflowNodeType, applyDagreLayout, calculateBranchFamilies, computeTimelineLayout, formatDuration, getBranchColor, getDisplayName, getNodeTypeStyle, groupSpansByKey, hasChildSpans, inferNodeType, makeGroupKey, useEvaluationContext, useSpanInfoContext, useTable, useTimelineLayout, useTimelineViewPreference, useTimelineZoom, useTraceDrawer, useTraceDrawerContext, useTraceListContext };