Skip to content

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

7.4 KB
Raw Blame
import type { ComponentType, ReactNode } from "react";
import type tailwindColors from "tailwindcss/colors";

export interface DataPoint {
  time_dimension: string | undefined;
  dimension: string | undefined;
  /**
   * `null` means "measured nothing here": the bucket exists but the metric has
   * no honest value (e.g. an average over zero events). Time-series charts
   * render it as a gap; it is never coerced to `0`. A point with `null` metric
   * AND no dimension is a pure bucket marker β€” it keeps the bucket on the time
   * axis without contributing a series. (LFE-10694)
   */
  metric: number | null | Array<Array<number>>;
}

/**
 * What a time-series chart shows for a (bucket, series) cell that has no data
 * point:
 * - `"zero"`: additive metrics (counts, sums) β€” zero events happened, so the
 *   honest value is a real `0` and the line stays continuous.
 * - `"gap"`: non-additive metrics (avg/min/max/percentiles) β€” no honest value
 *   exists, so the cell becomes `null` and the line breaks instead of
 *   fabricating a trend across the gap.
 *
 * The choice is a property of the metric's aggregation and is decided by the
 * caller (who knows it), not the chart. Defaults to `"gap"` β€” never invent a
 * number. (LFE-10694, manifesto V2)
 */
export type MissingBucketValue = "zero" | "gap";

/**
 * Whether a time-series chart shows its legend (always rendered below the
 * plot):
 * - `"auto"` (default): only when the chart draws more than one series β€” a
 *   multi-series chart is unreadable without one, while a single-series legend
 *   just echoes the card title.
 * - `"below"`: always.
 * - `"none"`: never.
 * (LFE-10576)
 */
export type LegendPosition = "auto" | "below" | "none";

/**
 * Whether a chart legend shows a per-series summary across its time buckets:
 * - `"sum"`: the additive total (event counts, token totals, cost) β€” reconciles
 *   with the card's headline number.
 * - `"none"`: no per-series summary (default).
 *
 * Only additive metrics get a legend value. A summary is deliberately *not*
 * offered for non-additive metrics (latency percentiles, scores): a cross-bucket
 * sum is meaningless for them, a correct average can't be computed here because
 * the upstream pipeline pads missing buckets with real `0`s (it would deflate the
 * mean), and an unlabeled non-sum number reads ambiguously. Such charts show the
 * bare series name (the `"none"` default). The mode is chosen per call-site
 * because additivity is a property of the metric's aggregation, decided upstream
 * of the chart. (LFE-10498, LFE-10549)
 */
export type LegendSummaryMode = "sum" | "none";

/**
 * How clicking a legend entry behaves on a multi-series time chart:
 * - `"highlight"` (default): clicking a series focuses it and mutes the rest;
 *   clicking again clears. All series stay rendered. (Historical behavior.)
 * - `"toggle"`: clicking a series shows/hides it; hidden series are dropped from
 *   the plot and greyed in the legend. Pairs with `maxVisibleSeries` to tame
 *   overloaded charts by hiding the long tail by default. (LFE-10549)
 */
export type LegendInteraction = "highlight" | "toggle";

export interface FormattedMetric {
  negative?: boolean;
  prefix?: string;
  main: string;
  suffix?: string;
}

export type FormatMetricOptions = {
  unit?: string;
  style: "full" | "compact";
  maxCharacters?: number;
  /**
   * `"cents"` rounds USD to two decimals and shows non-zero values below one
   * cent as `<$0.01`. By default values under $5 keep up to six decimals.
   */
  usdPrecision?: "cents";
};

export type MetricFormatterFunction = (
  value: number,
  options: FormatMetricOptions,
) => FormattedMetric;

/** ChartThresholdOperator picks the violation region a chart tints around a threshold. */
type ChartThresholdOperator = "GT" | "GTE" | "LT" | "LTE" | "EQ" | "NEQ";

/** ChartThresholdColor is one of Tailwind's palette family names. */
type ChartThresholdColor = {
  [K in keyof typeof tailwindColors]: (typeof tailwindColors)[K] extends Record<
    string,
    string
  >
    ? K
    : never;
}[keyof typeof tailwindColors] &
  string;

/** ChartThreshold renders a horizontal reference line plus an operator-derived tinted violation region. */
export interface ChartThreshold {
  value: number;
  operator: ChartThresholdOperator;
  color: ChartThresholdColor;
  label?: string;
}

export interface ChartProps {
  data: DataPoint[];
  config?: {
    [key: string]: {
      label?: ReactNode;
      icon?: ComponentType;
    } & (
      | { color?: string; theme?: never }
      | { color?: never; theme: Record<"light" | "dark", string> }
    );
  };
  accessibilityLayer?: boolean;
  metricFormatter?: MetricFormatterFunction;
  legendPosition?: LegendPosition;
  legendSummary?: LegendSummaryMode;
  /** How a legend click behaves (focus-vs-toggle). Defaults to `"highlight"`. */
  legendInteraction?: LegendInteraction;
  /**
   * Cap the number of series drawn by default (top-N by magnitude); the rest
   * start hidden but remain toggleable from the legend. Only meaningful with
   * `legendInteraction="toggle"`. Undefined = draw every series. (LFE-10549)
   */
  maxVisibleSeries?: number;
  /**
   * Recharts sync group for chart types that still use Recharts. Design-system
   * charts use `sync` to share their active key instead. (LFE-10549)
   */
  syncId?: string;
  sync?: {
    activeKey: string | undefined;
    onActiveKeyChange: (key: string | undefined) => void;
  };
  showValueLabels?: boolean;
  showDataPointDots?: boolean;
  thresholds?: ChartThreshold[];
  /** See {@link MissingBucketValue}. Defaults to `"gap"`. */
  missingValue?: MissingBucketValue;
  /**
   * Whether a line/area bridges `null` cells instead of breaking. Defaults to
   * `false`: drawing across a no-data bucket fabricates values that were never
   * measured. Opt in only when the series semantically continues across the
   * gap. (LFE-10694, manifesto V2)
   */
  connectNulls?: boolean;
  /**
   * Hide the x-axis tick labels on a categorical (entity-name) axis, keeping the
   * full name in the hover tooltip. Off by default. Opt in for the experiments /
   * dataset-compare charts, whose long entity names clutter the axis with little
   * value. Forwarded to `prepareTimeAxis` as `hideCategoryTickLabels`, so it only
   * affects a categorical axis β€” a temporal axis keeps its timestamp labels.
   */
  hideXAxisLabels?: boolean;
  /** compactYAxis shrinks the y-axis gutter to fit short tick labels. Consumed by LINE_TIME_SERIES. */
  compactYAxis?: boolean;
  /**
   * Give each bar of a categorical (entity) axis its own palette colour, plus a
   * legend below the plot that names it. Off by default: a dashboard bar chart
   * shows its categories on the axis and needs neither. Opt in where the axis
   * bars are entities rather than buckets β€” the experiments strip, one bar
   * per run. Colours and the optional legend both come from
   * `prepareCategoryBars`, which also decides when there are too many bars for
   * the bounded palette to identify any of them.
   */
  colorBarsByCategory?: boolean;
  /**
   * Measure the bars from zero instead of from a fitted domain. A bar
   * encodes its value as a length, so this is what makes two bars comparable at
   * all β€” on a fitted domain 0.80/0.87/1.00 draw as short/medium/full.
   *
   * Off by default only because it is a visible change to the bar charts that
   * already ship without it (the score-analytics dashboard widget), which are
   * out of scope here. Every vertical bar chart ought to have it.
   */
  zeroBaseline?: boolean;
}