Skip to content

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

TypeScript
20.6 KB
Raw Blame
/**
 * Chart.js plugins that put the numbers on the chart itself.
 *
 * A chart whose values can only be read off an axis degrades badly: shrunk into
 * a report page, or rendered where a tick label is missing, it stops carrying
 * information. These plugins print the value at each mark, the share on each
 * slice, and the reading inside a gauge, so the picture stays legible on its
 * own. They are written against the Chart.js element geometry rather than a
 * plugin package, so nothing is added to the dependency tree.
 */
import type { Chart, ChartType, Plugin } from 'chart.js'
import { logger } from '../logger'
import { CHART_FONT_STACK } from './fonts'

export type ValueFormat = 'auto' | 'plain' | 'compact' | 'currency' | 'percent'

export interface ValueLabelOptions {
  format: ValueFormat
  /** Prefix for `currency`, e.g. "$" or "€". */
  currencySymbol?: string
  decimals?: number
  textColor: string
  backgroundColor: string
  /** 'y' when bars grow horizontally, which moves labels past the bar end. */
  indexAxis?: 'x' | 'y'
  /** Multiplier tying label type to the canvas size, as the axes use. */
  fontScale?: number
  /** Set on each draw to how many values got no label. */
  unlabelled?: { count: number }
  /** Receives what could not be drawn, so the result can say it is missing. */
  failed?: string[]
}

/** Below this, money is grouped in full rather than abbreviated. */
const CURRENCY_ABBREVIATE_FROM = 100_000

const COMPACT_STEPS: Array<[number, string]> = [
  [1_000_000_000, 'B'],
  [1_000_000, 'M'],
  [1_000, 'K'],
]

/** Render one number the way a reader expects to see it on a chart. */
export function formatValue(value: number, o: ValueLabelOptions): string {
  if (!Number.isFinite(value)) return ''
  const decimals = o.decimals
  // A count the caller set prints exactly; a count guessed per value drops its
  // trailing zeros, so 45% does not read as 45.0%.
  const fixed = (n: number, d: number): string =>
    decimals !== undefined
      ? n.toFixed(d)
      : n
          .toFixed(d)
          .replace(/\.0+$/, '')
          .replace(/(\.\d*?)0+$/, '$1')

  switch (o.format) {
    case 'percent':
      return `${fixed(value, decimals ?? 1)}%`
    case 'currency': {
      const sym = o.currencySymbol ?? '$'
      const abs = Math.abs(value)
      const sign = value < 0 ? '-' : ''
      // Money reads better grouped until it gets long: $1,200 beats $1.2K,
      // while $120K beats $120,000 on a crowded axis.
      if (abs >= CURRENCY_ABBREVIATE_FROM) {
        for (const [step, suffix] of COMPACT_STEPS) {
          if (abs >= step) return `${sign}${sym}${fixed(abs / step, decimals ?? 1)}${suffix}`
        }
      }
      // Unless a count is set, cents are kept, both places: $4.99 must not read
      // as $5, nor $4.90 as $4.9.
      const places = decimals ?? (Number.isInteger(abs) ? 0 : Math.max(2, guessDecimals(abs)))
      const shown =
        decimals === undefined && places > 0
          ? abs.toFixed(places).replace(/(\.\d\d\d*?)0+$/, '$1')
          : fixed(abs, places)
      return `${sign}${sym}${group(shown)}`
    }
    case 'compact': {
      const abs = Math.abs(value)
      for (const [step, suffix] of COMPACT_STEPS) {
        if (abs >= step)
          return `${value < 0 ? '-' : ''}${fixed(abs / step, decimals ?? 1)}${suffix}`
      }
      return fixed(value, decimals ?? guessDecimals(value))
    }
    case 'plain':
      return group(fixed(value, decimals ?? guessDecimals(value)))
    case 'auto':
    default:
      return Math.abs(value) >= 10_000
        ? formatValue(value, { ...o, format: 'compact' })
        : group(fixed(value, decimals ?? guessDecimals(value)))
  }
}

/**
 * Enough decimal places for the value to survive rounding: a fixed count prints
 * 0.0012 as "0", so values below 1 get places by their order of magnitude.
 */
function guessDecimals(value: number): number {
  if (Number.isInteger(value)) return 0
  const abs = Math.abs(value)
  if (abs >= 10) return 1
  if (abs >= 1) return 2
  if (abs === 0) return 0
  // Two significant figures: 0.0012 -> 4 places, 0.5 -> 2.
  return Math.min(8, 1 - Math.floor(Math.log10(abs)))
}

function group(text: string): string {
  const [int, frac] = text.split('.')
  const sign = int.startsWith('-') ? '-' : ''
  const digits = sign ? int.slice(1) : int
  const grouped = digits.replace(/\B(?=(\d{3})+(?!\d))/g, ',')
  return `${sign}${grouped}${frac ? `.${frac}` : ''}`
}

/** Elements smaller than this are left unlabelled — the text would not fit. */
const MIN_ARC_SHARE = 0.04

/** Roughly how many value labels fit across a plot before they collide. */
const READABLE_LABEL_COUNT = 14

/**
 * Label every `stride`-th point. Returns 0 when the series is so dense that
 * even thinned labels would be noise rather than information.
 */
function labelStride(points: number): number {
  if (points <= READABLE_LABEL_COUNT) return 1
  const stride = Math.ceil(points / READABLE_LABEL_COUNT)
  return stride <= 3 ? stride : 0
}

interface Point {
  x: number
  y: number
}

interface Box {
  left: number
  top: number
  right: number
  bottom: number
}

function intersects(a: Box, b: Box): boolean {
  return a.left < b.right && b.left < a.right && a.top < b.bottom && b.top < a.bottom
}

/**
 * The column of a radial scale's tick labels, which runs straight up from the
 * centre of a polar area chart. Undefined on charts without one.
 */
function radialTickColumn(chart: Chart): Box | undefined {
  const r = (chart.scales as Record<string, unknown> | undefined)?.r as
    | {
        xCenter?: number
        yCenter?: number
        drawingArea?: number
        ticks?: Array<{ label?: unknown }>
        options?: { ticks?: { display?: boolean } }
      }
    | undefined
  if (!r || r.options?.ticks?.display === false) return undefined
  const { xCenter, yCenter, drawingArea } = r
  if (xCenter === undefined || yCenter === undefined || drawingArea === undefined) return undefined
  const widest = Math.max(
    0,
    ...(r.ticks ?? []).map(t => chart.ctx.measureText(String(t.label ?? '')).width)
  )
  const half = widest / 2 + 6
  return {
    left: xCenter - half,
    right: xCenter + half,
    top: yCenter - drawingArea - 12,
    bottom: yCenter,
  }
}

/** The rectangle of every drawn bar, with the element it belongs to. */
function barBoxes(chart: Chart, horizontal: boolean): Array<Box & { element: unknown }> {
  const out: Array<Box & { element: unknown }> = []
  chart.data.datasets.forEach((_, di) => {
    const meta = chart.getDatasetMeta(di)
    if (meta.hidden) return
    for (const element of meta.data) {
      const el = element as {
        x?: number
        y?: number
        base?: number
        width?: number
        height?: number
      }
      const thickness = horizontal ? el.height : el.width
      if (el.x === undefined || el.y === undefined || el.base === undefined) continue
      if (typeof thickness !== 'number' || !(thickness > 0)) continue
      out.push(
        horizontal
          ? {
              element,
              left: Math.min(el.x, el.base),
              right: Math.max(el.x, el.base),
              top: el.y - thickness / 2,
              bottom: el.y + thickness / 2,
            }
          : {
              element,
              left: el.x - thickness / 2,
              right: el.x + thickness / 2,
              top: Math.min(el.y, el.base),
              bottom: Math.max(el.y, el.base),
            }
      )
    }
  })
  return out
}

/** The legend and title boxes, which value labels must not print over. */
function reservedBoxes(chart: Chart): Box[] {
  const blocks = [
    (chart as { legend?: Partial<Box> }).legend,
    (chart as { titleBlock?: Partial<Box> }).titleBlock,
  ]
  return blocks.filter(
    (b): b is Box =>
      b !== undefined &&
      [b.left, b.top, b.right, b.bottom].every(v => typeof v === 'number') &&
      b.right! > b.left! &&
      b.bottom! > b.top!
  )
}

function isArcChart(type: ChartType | string): boolean {
  return type === 'pie' || type === 'doughnut' || type === 'polarArea'
}

/** Perceived lightness of a #rgb/#rrggbb fill, 0 (black) to 1 (white). */
function luminance(color: string): number | undefined {
  const hex = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i.exec(color.trim())
  if (!hex) return undefined
  let body = hex[1]
  if (body.length === 3)
    body = body
      .split('')
      .map(c => c + c)
      .join('')
  const r = parseInt(body.slice(0, 2), 16) / 255
  const g = parseInt(body.slice(2, 4), 16) / 255
  const b = parseInt(body.slice(4, 6), 16) / 255
  return 0.2126 * r + 0.7152 * g + 0.0722 * b
}

/** The fill this element was drawn with, when it resolves to a single color. */
function elementFill(element: unknown, index: number): string | undefined {
  const opts = (element as { options?: { backgroundColor?: unknown } }).options
  const bg = opts?.backgroundColor
  if (typeof bg === 'string') return bg
  if (Array.isArray(bg)) {
    const c = bg[index % bg.length]
    return typeof c === 'string' ? c : undefined
  }
  return undefined
}

/**
 * Draw each value beside its mark. Slice charts additionally get their share of
 * the total, which is the number a reader of a pie actually wants.
 */
export function valueLabelsPlugin(options: ValueLabelOptions): Plugin {
  return {
    id: 'clerumValueLabels',
    // After everything else, so scale ticks drawn above the data do not cover them.
    afterDraw(chart: Chart) {
      try {
        drawValueLabels(chart, options)
      } catch (err) {
        // A label is an enhancement; it never costs the whole render, but it is reported.
        decorationFailed(options.failed, 'value labels', err)
      }
    },
  }
}

function drawValueLabels(chart: Chart, o: ValueLabelOptions): void {
  const { ctx } = chart
  const arcs = isArcChart((chart.config as { type?: ChartType }).type ?? 'bar')

  // Each ring of a pie or doughnut is a whole of its own.
  const totals = chart.data.datasets.map(ds =>
    arcs
      ? (ds.data ?? []).reduce<number>(
          (sum, v) => sum + (typeof v === 'number' ? Math.abs(v) : 0),
          0
        )
      : 0
  )

  const points = chart.data.datasets.reduce((n, d) => n + (d.data?.length ?? 0), 0)
  const stride = labelStride(points)
  const unlabelled = o.unlabelled ?? { count: 0 }
  unlabelled.count = 0
  if (stride === 0) {
    unlabelled.count = chart.data.datasets.reduce(
      (n, d) => n + (d.data ?? []).filter(v => v !== null && v !== undefined).length,
      0
    )
    return
  }

  const size = Math.round(12 * (o.fontScale ?? 1))
  // Labels of different series can land on the same spot; the first one drawn
  // keeps it. In a bar chart a label may cover its own bar, never another.
  const taken = reservedBoxes(chart)
  const bars = arcs ? [] : barBoxes(chart, o.indexAxis === 'y')
  ctx.save()
  const ticks = arcs ? radialTickColumn(chart) : undefined
  ctx.font = `600 ${size}px ${CHART_FONT_STACK}`
  ctx.textAlign = 'center'
  ctx.textBaseline = 'middle'

  chart.data.datasets.forEach((dataset, di) => {
    const meta = chart.getDatasetMeta(di)
    if (meta.hidden) return

    const total = totals[di]
    meta.data.forEach((element, ei) => {
      const raw = dataset.data[ei]
      const value = typeof raw === 'number' ? raw : readY(raw)
      if (value === null) return
      const skip = () => {
        unlabelled.count++
      }
      // Keep the first and last of a thinned series so the range stays readable.
      if (stride > 1 && ei % stride !== 0 && ei !== meta.data.length - 1) return skip()

      let text = formatValue(value, o)
      if (arcs && total > 0) {
        text = `${text} (${((Math.abs(value) / total) * 100).toFixed(0)}%)`
      }
      if (!text) return

      if (arcs && total > 0 && Math.abs(value) / total < MIN_ARC_SHARE) return skip()
      const half = ctx.measureText(text).width / 2 + 2
      const spot = labelSpot(chart, element, arcs, o.indexAxis === 'y', half)
      if (!spot) return skip()
      const box = {
        left: spot.x - half,
        right: spot.x + half,
        top: spot.y - size / 2 - 1,
        bottom: spot.y + size / 2 + 1,
      }
      // A label on the tick column moves to the side of it its slice is on.
      const shifted = !!ticks && intersects(box, ticks)
      if (ticks && shifted) {
        const shift =
          spot.x < (ticks.left + ticks.right) / 2 ? ticks.left - box.right : ticks.right - box.left
        box.left += shift
        box.right += shift
        spot.x += shift
      }
      if (taken.some(other => intersects(box, other))) return skip()
      if (bars.some(bar => bar.element !== element && intersects(box, bar))) return skip()
      taken.push(box)

      // A label that lands on top of a filled slice has to invert; one that
      // sits in open plot area, or was moved off its slice, keeps the theme
      // color over a halo of the ground.
      let ink = o.textColor
      let halo = o.backgroundColor
      if (arcs && !shifted) {
        const light = luminance(elementFill(element, ei) ?? '')
        if (light !== undefined) {
          ink = light < 0.5 ? '#ffffff' : '#0f172a'
          halo = light < 0.5 ? '#00000055' : '#ffffff99'
        }
      }

      ctx.lineWidth = 3
      ctx.strokeStyle = halo
      ctx.strokeText(text, spot.x, spot.y)
      ctx.fillStyle = ink
      ctx.fillText(text, spot.x, spot.y)
    })
  })

  ctx.restore()
}

function readY(raw: unknown): number | null {
  // A floating bar is stored as [from, to]; the number worth printing is the
  // step it spans, which is what a waterfall is read for.
  if (Array.isArray(raw) && raw.length === 2) {
    const from = Number(raw[0])
    const to = Number(raw[1])
    return Number.isFinite(from) && Number.isFinite(to) ? to - from : null
  }
  if (raw && typeof raw === 'object' && 'y' in raw) {
    const y = (raw as { y: unknown }).y
    return typeof y === 'number' ? y : null
  }
  return null
}

/** Where the number goes for this element, in canvas coordinates. */
function labelSpot(
  chart: Chart,
  element: unknown,
  arcs: boolean,
  horizontal: boolean,
  halfWidth: number
): Point | undefined {
  const el = element as {
    x?: number
    y?: number
    base?: number
    getCenterPoint?: () => Point
  }

  if (arcs) {
    const centre = el.getCenterPoint?.()
    return centre ? { x: centre.x, y: centre.y } : undefined
  }

  if (el.x === undefined || el.y === undefined) return undefined
  const area = chart.chartArea

  // A horizontal bar grows along x, so its number sits just past the bar end.
  if (horizontal) {
    const outward = el.base !== undefined && el.x < el.base ? -(halfWidth + 6) : halfWidth + 6
    return { x: clampTo(el.x + outward, halfWidth, chart.width - halfWidth), y: el.y }
  }

  // Vertical bars and line points read best just above the mark; a negative bar
  // grows downward, so its label goes below.
  const offset = el.base !== undefined && el.y > el.base ? 14 : -12
  return {
    // Clamped against the canvas rather than the plot: a label on the first or
    // last mark sits over the axis gutter, but must not leave the image.
    x: clampTo(el.x, halfWidth, chart.width - halfWidth),
    y: clampTo(el.y + offset, area.top + 9, area.bottom - 9),
  }
}

function clampTo(v: number, lo: number, hi: number): number {
  return Math.min(Math.max(v, lo), hi)
}

/** Color distance below which two slice colors read as the same. */
const MIN_COLOR_DISTANCE = 48

function rgb(color: string): [number, number, number] | undefined {
  const hex = /^#([0-9a-f]{6})$/i.exec(color.trim())?.[1]
  if (!hex) return undefined
  return [0, 2, 4].map(i => parseInt(hex.slice(i, i + 2), 16)) as [number, number, number]
}

function mix(color: string, toward: string, share: number): string | undefined {
  const a = rgb(color)
  const b = rgb(toward)
  if (!a || !b) return undefined
  return `#${a
    .map((c, i) => Math.round(c + (b[i] - c) * share))
    .map(c => c.toString(16).padStart(2, '0'))
    .join('')}`
}

function distance(a: string, b: string): number {
  const x = rgb(a)
  const y = rgb(b)
  if (!x || !y) return a === b ? 0 : Infinity
  return Math.hypot(x[0] - y[0], x[1] - y[1], x[2] - y[2])
}

/**
 * One fill per slice: the caller's colors first, then the palette, then the
 * palette shaded toward and away from the background, skipping shades too close
 * to a color already used. Only when those run out do colors repeat, and then
 * never on the last slice, which sits beside the first.
 */
export function sliceColors(
  count: number,
  requested: ReadonlyArray<string | undefined> | undefined,
  palette: string[],
  background: string
): { colors: string[]; padded: boolean; repeated: boolean } {
  // A requested color stays on its slice; a slice without one takes the next
  // color the theme adds.
  const ownAt = (i: number) => (typeof requested?.[i] === 'string' ? requested[i] : undefined)
  const own = Array.from({ length: count }, (_, i) => ownAt(i)).filter(
    (c): c is string => c !== undefined
  )
  const light = (rgb(background) ?? [255, 255, 255]).reduce((sum, c) => sum + c, 0) > 382
  const shades = [
    ...palette.map(c => mix(c, background, 0.45)),
    ...palette.map(c => mix(c, light ? '#000000' : '#ffffff', 0.4)),
    ...palette.map(c => mix(c, background, 0.7)),
  ].filter((c): c is string => c !== undefined)
  const pool = [...own]
  for (const candidate of [...palette, ...shades]) {
    if (pool.length >= count) break
    if (pool.every(used => distance(used, candidate) >= MIN_COLOR_DISTANCE)) pool.push(candidate)
  }
  const distinct = pool.length
  let next = own.length
  const colors = Array.from({ length: count }, (_, i) => ownAt(i) ?? pool[next++ % distinct])
  if (count > distinct && count > 1 && colors[count - 1] === colors[0]) {
    colors[count - 1] = pool[Math.min(1, distinct - 1)]
  }
  return {
    colors,
    padded: requested !== undefined && own.length < count,
    repeated: count > distinct,
  }
}

export interface GaugeCenterOptions {
  value: number
  max: number
  textColor: string
  mutedColor: string
  format: ValueLabelOptions
  /** Receives what could not be drawn, so the result can say it is missing. */
  failed?: string[]
}

/** Record a decoration that could not be drawn: in the result, and in the log. */
function decorationFailed(failed: string[] | undefined, what: string, err: unknown): void {
  const message = err instanceof Error ? err.message : String(err)
  failed?.push(`${what} (${message})`)
  logger.warn({ decoration: what, err: message }, 'Chart decoration could not be drawn')
}

/**
 * Print the reading inside the dial. Without it a gauge shows a coloured arc
 * and no number, which is the one thing a gauge exists to communicate.
 */
export function gaugeCenterPlugin(o: GaugeCenterOptions): Plugin {
  return {
    id: 'clerumGaugeCenter',
    afterDatasetsDraw(chart: Chart) {
      try {
        const { ctx, chartArea } = chart
        const cx = (chartArea.left + chartArea.right) / 2
        // The dial is a half circle, so its visual centre sits low in the box.
        const cy = chartArea.bottom - (chartArea.bottom - chartArea.top) * 0.12
        const size = Math.max(18, Math.min(52, (chartArea.right - chartArea.left) / 9))

        ctx.save()
        ctx.textAlign = 'center'
        ctx.textBaseline = 'alphabetic'
        ctx.fillStyle = o.textColor
        ctx.font = `700 ${size}px ${CHART_FONT_STACK}`
        ctx.fillText(formatValue(o.value, o.format), cx, cy)
        ctx.fillStyle = o.mutedColor
        ctx.font = `500 ${Math.round(size * 0.42)}px ${CHART_FONT_STACK}`
        // Neutral rather than an English word: the caller's title and labels
        // may be in any language, and this sits inside the same picture.
        ctx.fillText(`/ ${formatValue(o.max, o.format)}`, cx, cy + size * 0.62)
        ctx.restore()
      } catch (err) {
        decorationFailed(o.failed, 'the gauge reading', err)
      }
    },
  }
}

/** Paint the theme background behind the plot. */
export function backgroundPlugin(color: string): Plugin {
  return {
    id: 'clerumBackground',
    beforeDraw(chart: Chart) {
      const { ctx } = chart
      ctx.save()
      ctx.globalCompositeOperation = 'destination-over'
      ctx.fillStyle = color
      ctx.fillRect(0, 0, chart.width, chart.height)
      ctx.restore()
    },
  }
}

/**
 * State the chart is empty instead of writing out a blank rectangle, so a
 * dataset that reduced to nothing is visible as such in the report.
 */
export function emptyStatePlugin(message: string, textColor: string): Plugin {
  return {
    id: 'clerumEmptyState',
    afterDraw(chart: Chart) {
      const { ctx, chartArea } = chart
      ctx.save()
      ctx.fillStyle = textColor
      ctx.font = `500 14px ${CHART_FONT_STACK}`
      ctx.textAlign = 'center'
      ctx.textBaseline = 'middle'
      ctx.fillText(
        message,
        (chartArea.left + chartArea.right) / 2,
        (chartArea.top + chartArea.bottom) / 2
      )
      ctx.restore()
    },
  }
}