🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.
TypeScript analyticsautogenevaluationlangchainlarge-language-modelsllama-indexllmllm-evaluationllm-observabilityllmopsmonitoringobservabilityopen-sourceopenaiplaygroundprompt-engineeringprompt-managementself-hostedycombinator
/* eslint-disable no-nested-ternary, @repo/component-file-structure */
/* eslint-disable @repo/no-style-props */
import { useMemo, useState, useCallback, type ReactNode } from "react";
import { type DashboardWidgetChartType } from "@langfuse/shared/src/db";
import { type OrderByState } from "@langfuse/shared";
import {
type QueryType,
type ViewVersion,
getResultUnit,
} from "@langfuse/shared/query";
import { useScheduledDashboardExecuteQuery } from "@/src/features/dashboard/hooks/DashboardQuerySchedulerProvider";
import { Chart } from "@/src/features/widgets/chart-library/Chart";
import {
type FormatMetricOptions,
type LegendPosition,
} from "@/src/features/widgets/chart-library/chart-props";
import { ChartLoadingState } from "@/src/features/widgets/chart-library/ChartLoadingState";
import {
getChartLoadingProgress,
getChartLoadingStateProps,
} from "@/src/features/widgets/chart-library/chartLoadingStateUtils";
import {
formatMetricName,
shouldUseWidgetSSE,
getWidgetMetricPresentation,
getWidgetMissingBucketValue,
type WidgetChartConfig,
} from "@/src/features/widgets/utils";
import { isTimeSeriesChart } from "@/src/features/widgets/chart-library/utils";
import { useReadPath } from "@/src/features/events/hooks/useReadPath";
import { cn } from "@/src/utils/tailwind";
// ============================================================================
// Types
// ============================================================================
interface WidgetMetricConfig {
measure: string;
agg: string;
}
interface WidgetDimensionConfig {
field: string;
}
export interface WidgetContentProps {
projectId: string;
query: QueryType;
version: ViewVersion;
chartType: DashboardWidgetChartType;
chartConfig: WidgetChartConfig;
metrics: WidgetMetricConfig[];
dimensions: WidgetDimensionConfig[];
view: string;
/**
* External loading state - when true, shows loading overlay even if query is complete.
* Useful when parent component needs to load data before the widget can be meaningful.
*/
isExternalLoading?: boolean;
/**
* Unique ID for query scheduling.
*/
schedulerId: string;
/**
* Layout hint for loading state display. Affects spacing and text size.
*/
layoutHint?: "default" | "compact" | "tight";
/**
* Pivot table sort state (only used for PIVOT_TABLE chart type)
*/
sortState?: OrderByState | null;
/**
* Callback when pivot table sort changes
*/
onSortChange?: (sort: OrderByState | null) => void;
/**
* Additional class names for the container
*/
className?: string;
/**
* Optional presentation-only labels for entity_dimension values.
*/
entityDimensionLabelMap?: Record<string, string>;
/**
* Optional presentation-only labels for the first dimension's values, e.g.
* names for ID breakdowns. Values without a label keep their raw value.
*/
dimensionLabelMap?: ReadonlyMap<string, string>;
/**
* Hide x-axis tick labels on a categorical (entity-name) axis; the full name
* stays in the hover tooltip. Off by default. Opt in on entity-dimension
* charts whose long names clutter the axis.
*/
hideXAxisLabels?: boolean;
/**
* Colour each bar of a categorical (entity) axis. Off by default; opt in on
* entity-dimension bar charts such as the experiments strip. See
* `prepareCategoryBars`.
*/
colorBarsByCategory?: boolean;
legendPosition?: LegendPosition;
/**
* Measure bars from zero rather than from a fitted domain. Off by default;
* see `ChartProps.zeroBaseline`.
*/
zeroBaseline?: boolean;
/**
* Replaces the chart's default "No data" card — for a widget in a band too
* short for it. Pass a stable node (see `Chart`).
*/
emptyState?: ReactNode;
usdPrecision?: FormatMetricOptions["usdPrecision"];
}
// ============================================================================
// Components
// ============================================================================
const getXAxisValue = (
item: Record<string, unknown>,
entityDimensionLabelMap?: Record<string, string>,
) => {
const entityDimensionValue = String(item["entity_dimension"]);
const entityDimensionLabel = entityDimensionLabelMap?.[entityDimensionValue];
return entityDimensionLabel && entityDimensionLabel.length > 0
? entityDimensionLabel
: entityDimensionValue;
};
/**
* Core widget content: executes query, transforms data, renders chart with loading states.
*
* This component handles:
* - Query execution via useScheduledDashboardExecuteQuery
* - Data transformation for chart consumption (time_dimension, entity_dimension, dimension, metric)
* - Chart rendering with the appropriate chart type
* - Loading and error states
*
* For pivot tables, pass sortState and onSortChange to enable sorting.
*/
export function WidgetContent({
projectId,
query,
version,
chartType,
chartConfig,
metrics,
dimensions,
view,
// equals widget is pending
isExternalLoading = false,
schedulerId,
layoutHint = "default",
sortState,
onSortChange,
className,
entityDimensionLabelMap,
dimensionLabelMap,
hideXAxisLabels,
colorBarsByCategory,
legendPosition,
zeroBaseline,
emptyState,
usdPrecision,
}: WidgetContentProps) {
// Transport-only: `version` is a prop here, so an unresolved session can
// never change WHAT is queried — only whether it streams (SSE) or not.
const { isV4 } = useReadPath();
const [retryCount, setRetryCount] = useState(0);
const handleRetry = useCallback(() => {
setRetryCount((current) => current + 1);
}, []);
// Execute the query
const queryResult = useScheduledDashboardExecuteQuery(
{
projectId,
version,
query,
},
{
trpc: {
context: {
skipBatch: true,
},
},
queryId: schedulerId,
meta: {
silentHttpCodes: [412, 422],
},
refreshKey: retryCount,
useSSE: shouldUseWidgetSSE({
isV4Enabled: isV4,
version,
}),
enabled: !isExternalLoading,
},
);
// Transform data for chart consumption
const transformedData = useMemo(() => {
if (!queryResult.data) {
return [];
}
const mapped = queryResult.data.map((item: Record<string, unknown>) => {
if (chartType === "PIVOT_TABLE") {
// For pivot tables, preserve all raw data fields
const timeDimension = item["time_dimension"];
return {
dimension:
dimensions.length > 0
? (dimensions[0]?.field ?? "dimension")
: "dimension",
metric: 0,
time_dimension:
typeof timeDimension === "string"
? timeDimension
: String(timeDimension ?? "n/a"),
...item,
};
}
// Regular chart processing
const metric = metrics.slice().shift() ?? {
measure: "count",
agg: "count",
};
const metricField = `${metric.agg}_${metric.measure}`;
const metricValue = item[metricField];
const dimensionField = dimensions.slice().shift()?.field ?? "none";
// Handle x-axis: prefer entity_dimension, then time_dimension
let xAxisValue: string | undefined;
if (item["entity_dimension"] !== undefined) {
xAxisValue = getXAxisValue(item, entityDimensionLabelMap);
} else if (item["time_dimension"] !== undefined) {
xAxisValue = String(item["time_dimension"]);
}
const isTimeSeries = isTimeSeriesChart(chartType);
const dimensionValue = item[dimensionField];
// A gap-filled empty bucket arrives as a row with no dimension and the
// metric column's type default: NULL for nullable aggregations
// (avg/percentiles), 0 for non-nullable ones (count/uniq/sum). Keep it
// as a pure bucket marker (holds the spot on the x axis) instead of
// inventing an "n/a" series. The 0 form is only treated as filler for
// additive metrics, where the marker is lossless (prepareDenseSeries
// re-derives the honest 0 for any series that exists); a real
// dimension-less avg/percentile 0 stays a visible data point. (LFE-10694)
const isFillerMetricValue =
metricValue == null ||
(getWidgetMissingBucketValue(metric.agg) === "zero" &&
Number(metricValue) === 0);
if (
isTimeSeries &&
(dimensionValue === null || dimensionValue === "") &&
isFillerMetricValue
) {
return {
time_dimension: xAxisValue,
dimension: undefined,
metric: null,
};
}
// A non-time-series chart draws `dimension` on its categorical axis, and
// on an entity query the ENTITY *is* that category — so hand it over as
// the dimension rather than the metric's name, which would collapse every
// entity into one bar. Only when the query has no breakdown of its own:
// that breakdown is the real series (categorical scores).
const entityIsCategory =
!isTimeSeries &&
item["entity_dimension"] !== undefined &&
dimensions.length === 0;
// Handle series dimension (for legend)
let seriesDimension: string;
if (entityIsCategory) {
seriesDimension = xAxisValue ?? "Unknown";
} else if (dimensionValue !== undefined) {
const val = dimensionValue;
// Empty first: "" is a string, so the order matters. (LFE-10694)
if (val === null || val === undefined || val === "") {
seriesDimension = "n/a";
} else if (typeof val === "string") {
seriesDimension = dimensionLabelMap?.get(val) ?? val;
} else if (Array.isArray(val)) {
seriesDimension = val.join(", ");
} else {
seriesDimension = String(val);
}
} else {
seriesDimension = formatMetricName(metricField);
}
return {
// time_dimension is used as x-axis for charts (works for both time and entity dimensions)
time_dimension: xAxisValue,
dimension: seriesDimension,
metric: Array.isArray(metricValue)
? metricValue
: // On a time series a missing value stays null — the chart renders
// it by the metric's missing-bucket semantics instead of a fake 0.
isTimeSeries && metricValue == null
? null
: Number(metricValue || 0),
};
});
// Entity-dimension charts have no meaningful query-side order (the server
// falls back to first-metric DESC, which differs per chart). Order the
// x-axis by the caller's entityDimensionLabelMap insertion order, so the
// caller decides what left-to-right means (the experiments strip makes it
// chronological). Entities the map doesn't know sort last.
if (
chartType !== "PIVOT_TABLE" &&
entityDimensionLabelMap &&
Object.keys(entityDimensionLabelMap).length > 0
) {
const order = new Map<string, number>();
Object.entries(entityDimensionLabelMap).forEach(([id, name], index) => {
order.set(id, index);
order.set(name, index);
});
return mapped
.slice()
.sort(
(a, b) =>
(order.get(a.time_dimension ?? "") ?? Number.MAX_SAFE_INTEGER) -
(order.get(b.time_dimension ?? "") ?? Number.MAX_SAFE_INTEGER),
);
}
return mapped;
}, [
queryResult.data,
chartType,
metrics,
dimensions,
entityDimensionLabelMap,
dimensionLabelMap,
]);
// Chart presentation (label and formatter)
const chartPresentation = useMemo(() => {
if (chartType === "PIVOT_TABLE" || metrics.length === 0) {
return undefined;
}
const metric = metrics[0];
return getWidgetMetricPresentation({
metric,
view,
version,
usdPrecision,
});
}, [chartType, metrics, view, version, usdPrecision]);
// Loading state
const chartLoadingState = getChartLoadingStateProps({
isPending: queryResult.isPending,
isError: queryResult.isError,
errorMessage: queryResult.error,
});
const usesBackendProgress = shouldUseWidgetSSE({
isV4Enabled: isV4,
version,
});
const loadingProgress = getChartLoadingProgress({
isPending: queryResult.isPending,
progress: queryResult.progress,
useBackendProgress: usesBackendProgress,
});
// Determine row limit
const effectiveRowLimit = useMemo(() => {
if (
chartType === "LINE_TIME_SERIES" ||
chartType === "BAR_TIME_SERIES" ||
chartType === "AREA_TIME_SERIES"
) {
return 100;
}
return chartConfig.row_limit ?? 100;
}, [chartType, chartConfig.row_limit]);
// Build chart config with units
const fullChartConfig = useMemo(() => {
const baseConfig = { ...chartConfig };
if (chartType === "PIVOT_TABLE") {
return {
...baseConfig,
dimensions: dimensions.map((dim) => dim.field),
metrics: metrics.map((m) => `${m.agg}_${m.measure}`),
units: metrics.map((m) =>
getResultUnit(view, m.measure, m.agg, version),
),
};
}
if (metrics.length > 0) {
return {
...baseConfig,
unit: getResultUnit(view, metrics[0].measure, metrics[0].agg, version),
};
}
return baseConfig;
}, [chartConfig, chartType, dimensions, metrics, view, version]);
if (isExternalLoading) {
return (
<div className="bg-background flex items-center justify-center rounded-lg border p-4">
<div className="text-muted-foreground">Loading...</div>
</div>
);
}
return (
<div className={cn("relative min-h-0 flex-1", className)}>
<Chart
chartType={chartType}
data={transformedData}
config={
chartPresentation
? { metric: { label: chartPresentation.label } }
: undefined
}
rowLimit={effectiveRowLimit}
chartConfig={fullChartConfig}
sortState={chartType === "PIVOT_TABLE" ? sortState : undefined}
onSortChange={chartType === "PIVOT_TABLE" ? onSortChange : undefined}
isLoading={queryResult.isPending || isExternalLoading}
metricFormatter={chartPresentation?.metricFormatter}
missingValue={getWidgetMissingBucketValue(metrics[0]?.agg ?? "count")}
hideXAxisLabels={hideXAxisLabels}
colorBarsByCategory={colorBarsByCategory}
legendPosition={legendPosition}
zeroBaseline={zeroBaseline}
emptyState={emptyState}
/>
{chartLoadingState.isLoading && (
<ChartLoadingState
showSpinner={chartLoadingState.showSpinner}
showHintImmediately={chartLoadingState.showHintImmediately}
hintText={chartLoadingState.hintText}
onRetry={queryResult.isError ? handleRetry : undefined}
progress={loadingProgress}
layout={layoutHint}
className="bg-background/80 absolute inset-0 z-20 backdrop-blur-xs"
/>
)}
</div>
);
}