Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript
17.7 KB
Raw Blame
/**
 * Chart preparation for `clerum__generate_dashboard`: each chart is validated
 * and translated to a configuration Chart.js registers before the page is
 * written, so an unusable chart becomes a note in its own card and a warning
 * for the agent instead of an error that stops the page script.
 */
import { colorWarnings, withoutInvalidColors } from './chartColors'
import { ChartDataError, coerceNumber, normalizeChartData } from './chartData'
import type { NormalizedDataset, NormalizedPoint } from './chartData'
import { escapeHtml } from './dashboardHtml'
import { DASHBOARD_CHART_TYPES } from './dashboardVocabulary'
import { TINT_ALPHA, filled, seriesDefaults } from './seriesPaint'

export { DASHBOARD_CHART_TYPES } from './dashboardVocabulary'

const KNOWN_TYPES = new Set<string>(DASHBOARD_CHART_TYPES)
const SLICE_TYPES = new Set(['pie', 'doughnut', 'polarArea'])
const XY_TYPES = new Set(['scatter', 'bubble'])

/**
 * What the page script needs to draw one chart. Colors are left as tokens
 * ("$chart-0", "[email protected]", "$success") that the script resolves against
 * the page's CSS variables, so the series follow light, dark and print modes.
 */
export interface ClientChart {
  id: string
  type: string
  labels: string[]
  datasets: Array<Record<string, unknown>>
  axes: 'cartesian' | 'radial' | 'none'
  indexAxis: 'x' | 'y'
  stacked: boolean
  legend: boolean
  xAxisLabel?: string
  yAxisLabel?: string
  gauge?: { value: string; max: string }
  /** Radius in pixels of a scatter or bubble chart's largest mark, hovered. */
  markRadius?: number
}

/** The number of series colors each theme defines (DashboardThemeColors.chart). */
const PALETTE_SIZE = 7

/**
 * The palette token for series or slice `i`. Past the palette the colors
 * repeat fainter each round, with a dash for lines, so the first 21 series look
 * different; later ones repeat.
 */
function paletteColor(i: number, alpha = 1): { color: string; dash?: number[] } {
  const round = Math.floor(i / PALETTE_SIZE)
  const shade = alpha * Math.max(0.35, 1 - 0.3 * round)
  const base = `$chart-${i % PALETTE_SIZE}`
  return {
    color: shade === 1 ? base : `${base}@${Number(shade.toFixed(2))}`,
    dash:
      round === 0
        ? undefined
        : [
            [6, 3],
            [2, 3],
            [8, 3, 2, 3],
          ][(round - 1) % 3],
  }
}

/** The values of a chart as a table, shown when Chart.js is not inlined. */
interface ValueTable {
  labels: string[]
  series: Array<{ label: string; values: string[] }>
}

interface Translated {
  chart: Omit<ClientChart, 'id'>
  warnings: string[]
  /** What a composed chart draws, for the table shown in its place; others list their series. */
  table?: ValueTable
}

function isRecord(value: unknown): value is Record<string, unknown> {
  return value !== null && typeof value === 'object' && !Array.isArray(value)
}

function optionalText(value: unknown): string | undefined {
  if (typeof value === 'string') return value.trim() ? value : undefined
  if (typeof value === 'number' && Number.isFinite(value)) return String(value)
  return undefined
}

function seriesColors(ds: NormalizedDataset, index: number, type: string): Record<string, unknown> {
  if (SLICE_TYPES.has(type)) {
    return {
      backgroundColor: ds.backgroundColor ?? ds.data.map((_, j) => paletteColor(j).color),
      borderColor: ds.borderColor ?? '$surface',
    }
  }
  const { color, dash } = paletteColor(index)
  // Shared with the PNG renderer (seriesPaint.ts).
  const paint = seriesDefaults(type, ds, { color, tint: paletteColor(index, TINT_ALPHA).color })
  const dashed = dash && ds.borderColor === undefined ? { borderDash: dash } : {}
  return {
    borderColor: filled(ds.borderColor, paint.borderColor, color),
    backgroundColor: filled(ds.backgroundColor, paint.backgroundColor, color),
    ...(paint.pointBackgroundColor ? { pointBackgroundColor: paint.pointBackgroundColor } : {}),
    ...(paint.borderWidth ? { borderWidth: paint.borderWidth } : {}),
    ...dashed,
  }
}

/**
 * `ds` without the colors that are not CSS colors (chartColors.ts); a slice
 * with no usable color, or none of its own, takes its palette color.
 */
function checkColors(
  ds: NormalizedDataset,
  index: number,
  type: string,
  where: string,
  bad: Array<{ at: string; value: unknown }>
): NormalizedDataset {
  const out = withoutInvalidColors(ds, index, where, bad)
  if (!SLICE_TYPES.has(type)) return out
  for (const key of ['backgroundColor', 'borderColor'] as const) {
    const value = out[key]
    if (Array.isArray(value)) out[key] = value.map((v, j) => v ?? paletteColor(j).color)
  }
  return out
}

function readout(n: number): string {
  return Number.isInteger(n) ? String(n) : String(Number(n.toFixed(2)))
}

/** `n` at full precision, without the noise of adding binary fractions (0.1 + 0.2). */
function plainNumber(n: number): string {
  return String(Number(n.toPrecision(12)))
}

function firstSeriesValues(ds: NormalizedDataset | undefined): number[] {
  return ((ds?.data ?? []) as Array<number | null>).map(v => (typeof v === 'number' ? v : 0))
}

/** Map a validated user-facing chart onto the Chart.js configuration that draws it. */
function translate(
  type: string,
  spec: Record<string, unknown>,
  labels: string[],
  datasets: NormalizedDataset[]
): Translated {
  const warnings: string[] = []
  const chart: Omit<ClientChart, 'id'> = {
    type,
    labels,
    datasets: [],
    axes: SLICE_TYPES.has(type) ? 'none' : type === 'radar' ? 'radial' : 'cartesian',
    indexAxis: 'x',
    stacked: false,
    legend: SLICE_TYPES.has(type) || datasets.some(ds => Boolean(ds.label)),
    xAxisLabel: optionalText(spec.xAxisLabel),
    yAxisLabel: optionalText(spec.yAxisLabel),
  }
  if (type === 'polarArea') chart.axes = 'radial'

  const styled = (ds: NormalizedDataset, i: number, as = type): Record<string, unknown> => ({
    ...ds,
    label: ds.label ?? '',
    ...seriesColors(ds, i, as),
  })

  switch (type) {
    case 'horizontalBar':
      chart.type = 'bar'
      chart.indexAxis = 'y'
      chart.datasets = datasets.map((ds, i) => styled(ds, i))
      return { chart, warnings }
    case 'area':
      chart.type = 'line'
      chart.datasets = datasets.map((ds, i) => ({ ...styled(ds, i), fill: ds.fill ?? true }))
      return { chart, warnings }
    case 'stackedBar':
      chart.type = 'bar'
      chart.stacked = true
      chart.datasets = datasets.map((ds, i) => styled(ds, i))
      return { chart, warnings }
    case 'stackedArea':
      chart.type = 'line'
      chart.stacked = true
      chart.datasets = datasets.map((ds, i) => ({
        ...styled(ds, i),
        fill: ds.fill ?? (i === 0 ? 'origin' : '-1'),
      }))
      return { chart, warnings }
    case 'mixedBarLine':
      chart.type = 'bar'
      // A lower order draws later, which keeps the lines above the bars.
      chart.datasets = datasets.map((ds, i) =>
        i === 0
          ? { ...styled(ds, i, 'bar'), order: 1 }
          : { ...styled(ds, i, 'line'), type: 'line', fill: false, order: 0 }
      )
      return { chart, warnings }
    case 'funnel': {
      chart.type = 'bar'
      chart.indexAxis = 'y'
      chart.legend = false
      const first = datasets[0]
      const pairs = firstSeriesValues(first).map((v, i) => ({ v, l: labels[i] ?? '', i }))
      pairs.sort((a, b) => b.v - a.v)
      chart.labels = pairs.map(p => p.l)
      // Per-stage colors follow their stage through the sort, as in the PNG
      // funnel; a short list wraps as Chart.js wraps it.
      const follow = (colors: string | Array<string | undefined> | undefined) =>
        Array.isArray(colors) && colors.length > 0
          ? pairs.map(p => colors[p.i % colors.length])
          : colors
      const stages = {
        ...first,
        data: pairs.map(p => p.v),
        backgroundColor: follow(first?.backgroundColor),
        borderColor: follow(first?.borderColor),
      }
      chart.datasets = [{ ...styled(stages, 0, 'bar'), label: '' }]
      const table = {
        labels: chart.labels,
        series: [{ label: first?.label ?? '', values: stages.data.map(String) }],
      }
      return { chart, warnings, table }
    }
    case 'waterfall': {
      chart.type = 'bar'
      chart.legend = false
      const deltas = firstSeriesValues(datasets[0])
      const floats: number[][] = []
      const colors: string[] = []
      let total = 0
      for (const delta of deltas) {
        floats.push([total, total + delta])
        colors.push(delta >= 0 ? '$success' : '$danger')
        total += delta
      }
      floats.push([0, total])
      colors.push('$chart-0')
      chart.labels = [...labels, 'Total']
      const table = {
        labels: chart.labels,
        series: [
          { label: datasets[0]?.label ?? '', values: [...deltas.map(String), plainNumber(total)] },
        ],
      }
      chart.datasets = [
        {
          label: datasets[0]?.label ?? '',
          data: floats,
          backgroundColor: colors,
          borderColor: colors,
        },
      ]
      return { chart, warnings, table }
    }
    case 'gauge': {
      chart.type = 'doughnut'
      chart.axes = 'none'
      chart.legend = false
      const requestedMax = coerceNumber(spec.gaugeMax)
      const max = requestedMax !== undefined && requestedMax > 0 ? requestedMax : 100
      if (max !== requestedMax && spec.gaugeMax !== undefined && spec.gaugeMax !== null) {
        warnings.push(`gaugeMax ${String(spec.gaugeMax)} is not a positive number; used 100.`)
      }
      // The first number sent, as the PNG gauge reads it; a gap is no reading.
      const values = ((datasets[0]?.data ?? []) as Array<number | null>).filter(
        (v): v is number => typeof v === 'number'
      )
      const raw = values[0] ?? 0
      if (values.length > 1) {
        warnings.push(
          `the gauge shows one value, so ${values.length - 1} more in datasets[0].data ` +
            `${values.length > 2 ? 'were' : 'was'} left out. ` +
            'Send one value, or use a bar chart to compare several.'
        )
      }
      const value = Math.min(Math.max(raw, 0), max)
      if (value !== raw) {
        warnings.push(
          `the gauge value ${raw} is outside 0..${max}, so the dial is drawn ` +
            `${value === 0 ? 'empty' : 'full'} and the readout shows ${readout(raw)}.`
        )
      }
      chart.labels = labels.length > 0 ? [labels[0], ''] : ['', '']
      chart.datasets = [
        {
          label: datasets[0]?.label ?? '',
          data: [value, max - value],
          backgroundColor: ['$chart-0', '$border'],
          borderColor: ['$chart-0', '$border'],
        },
      ]
      chart.gauge = { value: readout(raw), max: readout(max) }
      const table = {
        // A gauge sent with no labels has only a numbered position, which names nothing.
        labels: [Array.isArray(spec.labels) ? chart.labels[0] : '', 'Max'],
        series: [{ label: datasets[0]?.label ?? '', values: [chart.gauge.value, chart.gauge.max] }],
      }
      return { chart, warnings, table }
    }
    default:
      chart.datasets = datasets.map((ds, i) => styled(ds, i))
      if (XY_TYPES.has(type)) chart.markRadius = largestMark(type, datasets)
      return { chart, warnings }
  }
}

// Chart.js draws a point 3 px across by default and grows a hovered mark by 4
// px, with a border of 1 px.
const POINT_RADIUS = 3
const HOVER_GROWTH = 4
const MARK_BORDER = 1

/** Radius in pixels of the largest mark a scatter or bubble chart draws when hovered. */
function largestMark(type: string, datasets: NormalizedDataset[]): number {
  let largest = POINT_RADIUS
  if (type === 'bubble') {
    for (const ds of datasets) {
      for (const point of ds.data as NormalizedPoint[]) {
        if (point.r !== undefined && point.r > largest) largest = point.r
      }
    }
  }
  return largest + HOVER_GROWTH + MARK_BORDER
}

function valueTable(type: string, labels: string[], datasets: NormalizedDataset[]): ValueTable {
  if (XY_TYPES.has(type)) {
    const points = Math.max(...datasets.map(ds => ds.data.length))
    return {
      labels: Array.from({ length: points }, (_, i) => String(i + 1)),
      series: datasets.map(ds => ({
        label: ds.label ?? '',
        values: (ds.data as NormalizedPoint[]).map(p =>
          p.r === undefined ? `(${p.x}, ${p.y})` : `(${p.x}, ${p.y}, ${p.r})`
        ),
      })),
    }
  }
  return {
    labels,
    series: datasets.map(ds => ({
      label: ds.label ?? '',
      values: (ds.data as Array<number | null>).map(v => (v === null ? '' : String(v))),
    })),
  }
}

export interface PreparedChart {
  title?: string
  /** Text under the chart: a gauge's label. */
  caption?: string
  chart?: Omit<ClientChart, 'id'>
  table?: ValueTable
  error?: string
  warnings: string[]
}

/** Validate one chart spec found at `where` in the arguments. */
export function prepareDashboardChart(raw: unknown, where: string): PreparedChart {
  if (!isRecord(raw)) {
    return {
      warnings: [],
      error: `${where} must be a chart object {type, labels, datasets}; received ${
        raw === undefined
          ? 'nothing'
          : raw === null
            ? 'null'
            : Array.isArray(raw)
              ? 'an array'
              : `a ${typeof raw}`
      }.`,
    }
  }
  const title = optionalText(raw.title)
  const type = typeof raw.type === 'string' ? raw.type : undefined
  if (!type || !KNOWN_TYPES.has(type)) {
    const got = type ? `"${type}" is not a chart type` : 'is missing'
    return {
      title,
      warnings: [],
      error: `${where}.type ${got}; use one of: ${DASHBOARD_CHART_TYPES.join(', ')}.`,
    }
  }
  try {
    const clean = normalizeChartData(
      { labels: raw.labels, datasets: raw.datasets },
      { chartType: type, path: where }
    )
    const labels = clean.labels ?? []
    // A gauge draws one value, so it has no categories to label.
    const unlabeledGauge = type === 'gauge' && raw.labels === undefined
    const warnings = clean.warnings
      .filter(w => !(unlabeledGauge && w.includes(`\`${where}.labels\``)))
      .map(w => (w.includes(where) ? w : `${where}: ${w}`))
    const badColors: Array<{ at: string; value: unknown }> = []
    const datasets = clean.datasets.map((ds, i) => checkColors(ds, i, type, where, badColors))
    warnings.push(...colorWarnings(badColors, where))
    const slices = SLICE_TYPES.has(type)
    const colored = slices
      ? datasets.reduce((n, ds) => (ds.backgroundColor ? n : Math.max(n, ds.data.length)), 0)
      : datasets.length
    const paletted = slices || datasets.slice(PALETTE_SIZE).some(ds => !ds.borderColor)
    if (colored > PALETTE_SIZE && paletted && !['gauge', 'waterfall', 'funnel'].includes(type)) {
      const what = slices ? 'slices' : 'series'
      const past =
        colored === PALETTE_SIZE + 1
          ? `${what} ${colored} repeats one in a fainter shade`
          : `${what} ${PALETTE_SIZE + 1}-${colored} repeat them in fainter shades`
      warnings.push(
        `${where} has ${colored} ${what} and the palette ${PALETTE_SIZE} colors, so ${past}. ` +
          `Fewer ${what} read better.`
      )
    }
    const translated = translate(type, raw, labels, datasets)
    warnings.push(...translated.warnings.map(w => `${where}: ${w}`))
    return {
      title,
      caption:
        type === 'gauge' && Array.isArray(raw.labels) ? optionalText(raw.labels[0]) : undefined,
      chart: translated.chart,
      table: translated.table ?? valueTable(type, labels, datasets),
      warnings,
    }
  } catch (err) {
    if (!(err instanceof ChartDataError)) throw err
    return { title, warnings: [], error: err.message }
  }
}

function valueTableHtml(table: ValueTable): string {
  const head = `<tr><th></th>${table.series.map(s => `<th>${escapeHtml(s.label)}</th>`).join('')}</tr>`
  const rows = table.labels
    .map(
      (label, i) =>
        `<tr><td>${escapeHtml(label)}</td>${table.series
          .map(s => `<td>${escapeHtml(s.values[i] ?? '')}</td>`)
          .join('')}</tr>`
    )
    .join('')
  return `<div class="chart-card__table"><table class="data-table"><thead>${head}</thead><tbody>${rows}</tbody></table></div>`
}

/**
 * The charts of one dashboard. Each `card` call validates a spec and returns
 * its card; the specs Chart.js has to draw accumulate in `specs`.
 */
export class DashboardCharts {
  readonly specs: ClientChart[] = []
  drawn = 0

  /**
   * @param drawInBrowser false when Chart.js is not inlined: cards then carry a table of their values.
   * @param notes where repairs (`warnings`) and charts that could not be drawn (`failures`) are reported.
   */
  constructor(
    private readonly drawInBrowser: boolean,
    private readonly notes: { warnings: string[]; failures: string[] }
  ) {}

  card(raw: unknown, where: string, opts: { title?: string; tall?: boolean } = {}): string {
    const prepared = prepareDashboardChart(raw, where)
    this.notes.warnings.push(...prepared.warnings)
    const title = opts.title ?? prepared.title
    const heading = title ? `<h3 class="chart-card__title">${escapeHtml(title)}</h3>` : ''
    const wide = opts.tall ? ' chart-card--wide' : ''
    let body: string
    if (!prepared.chart) {
      this.notes.failures.push(prepared.error!)
      body = `<p class="chart-card__note">${escapeHtml(`This chart could not be drawn: ${prepared.error}`)}</p>`
    } else if (!this.drawInBrowser) {
      this.drawn++
      body = valueTableHtml(prepared.table!)
    } else {
      this.drawn++
      const id = `chart-${this.specs.length}`
      this.specs.push({ id, ...prepared.chart })
      const tall = opts.tall ? ' chart-card__container--tall' : ''
      const caption = prepared.caption
        ? `<p class="chart-card__caption">${escapeHtml(prepared.caption)}</p>`
        : ''
      body = `<div class="chart-card__container${tall}"><canvas id="${id}" role="img" aria-label="${escapeHtml(title ?? prepared.caption ?? '')}"></canvas></div>${caption}`
    }
    return `<div class="chart-card${wide}">${heading}${body}</div>`
  }
}