Skip to content

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

TypeScript
10.8 KB
Raw Blame
/**
 * Native (editable) PowerPoint charts for clerum__generate_pptx.
 *
 * The data goes through the same normalizer as clerum__generate_chart, because
 * PowerPoint drops chart-cache values written as text such as "1,200".
 */
import type PptxGenJS from 'pptxgenjs'
import { ChartDataError, normalizeChartData } from './chartData'
import type { PptxDeck } from './pptxDraw'
import { PPTX_FONT_FACE } from './pptxText'
import { NATIVE_CHART_TYPES } from './pptxVocabulary'

export type NativeChartType = (typeof NATIVE_CHART_TYPES)[number]

const SLICE_TYPES = new Set<NativeChartType>(['pie', 'doughnut'])

/** Series longer than this get no value labels; they would overlap. */
const MAX_LABELLED_POINTS = 12

export interface NativeChart {
  type: NativeChartType
  labels: string[]
  series: Array<{ name: string; values: Array<number | null> }>
}

export class ChartSpecError extends Error {}

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

/**
 * The native chart `raw` describes, or undefined when it carries no data at
 * all. Throws ChartSpecError, naming the field under `where`, for a type
 * PowerPoint cannot draw natively or data no chart can be drawn from.
 */
export function readNativeChart(
  raw: Record<string, unknown>,
  where: string,
  warnings: string[]
): NativeChart | undefined {
  const nested = isRecord(raw.data) ? raw.data : undefined
  // Labels and datasets are each read where they were given, nested or at the top.
  const labelsFrom = nested?.labels !== undefined ? nested : raw
  const datasetsFrom = nested?.datasets !== undefined ? nested : raw
  if (datasetsFrom.datasets === undefined && labelsFrom.labels === undefined) return undefined

  let type: NativeChartType
  if (raw.type === undefined || raw.type === null || raw.type === '') {
    type = 'bar'
    warnings.push(`${where}.type was missing, so a bar chart was drawn; set type to choose one.`)
  } else if ((NATIVE_CHART_TYPES as readonly unknown[]).includes(raw.type)) {
    type = raw.type as NativeChartType
  } else {
    throw new ChartSpecError(
      `${where}.type ${JSON.stringify(raw.type)} has no native PowerPoint chart. Use one of ` +
        `${NATIVE_CHART_TYPES.join(', ')}; for any other type, draw it with ` +
        `clerum__generate_chart and pass the file name it returns as ${where}.path.`
    )
  }

  const baseOf = (from: Record<string, unknown>) => (from === nested ? `${where}.data` : where)
  const base = baseOf(datasetsFrom)
  // Template charts leave the nested form out of the schema, so its labels are checked here.
  if (nested) checkNestedLabels(nested, `${where}.data`)
  const rewrite = (message: string) =>
    message
      .replace(/\bdata\.labels\b/g, `${baseOf(labelsFrom)}.labels`)
      .replace(/\bdata\.datasets\b/g, `${base}.datasets`)
      .replace(/`data`/g, `\`${base}\``)
  // Only what is drawn is read: a pie or doughnut draws its first series, and
  // a native chart takes its colors from the palette. A series left out then
  // neither sets the decimal convention, adds a category nor rejects the
  // chart, and the colors sent stay in the "Ignored arguments" note.
  const sent = datasetsFrom.datasets
  const drawn = Array.isArray(sent) && SLICE_TYPES.has(type) ? sent.slice(0, 1) : sent
  const datasets = Array.isArray(drawn)
    ? drawn.map(d => (isRecord(d) ? { label: d.label, data: d.data } : d))
    : drawn
  let normalized
  try {
    normalized = normalizeChartData({ labels: labelsFrom.labels, datasets }, { chartType: type })
  } catch (err) {
    if (err instanceof ChartDataError) throw new ChartSpecError(rewrite(err.message))
    throw err
  }
  for (const w of normalized.warnings) {
    const text = rewrite(w)
    warnings.push(text.includes(where) ? text : `${where}: ${text}`)
  }

  const unnamed = normalized.datasets.filter(d => !d.label).length
  if (unnamed > 0 && normalized.datasets.length > 1) {
    warnings.push(
      `${base}.datasets: ${unnamed} series had no label, so the legend numbers them; give each a label.`
    )
  }
  const series = normalized.datasets.map((d, i) => ({
    name: boundLabel(d.label || `#${i + 1}`, MAX_SERIES_NAME),
    values: d.data as Array<number | null>,
  }))
  if (Array.isArray(sent) && sent.length > series.length) {
    warnings.push(
      `${where}: a ${type} chart draws one series, so only "${series[0].name}" was drawn and ` +
        `${sent.length - series.length} more were left out. Use a bar or line chart to compare series.`
    )
  }
  const labels = (normalized.labels ?? []).map(l => boundLabel(l, MAX_CATEGORY_LABEL))
  return { type, labels, series }
}

function checkNestedLabels(data: Record<string, unknown>, base: string): void {
  if (Array.isArray(data.labels)) {
    data.labels.forEach((label, i) => {
      if (typeof label !== 'string' && typeof label !== 'number') {
        throw new ChartSpecError(`${base}.labels[${i}] must be text or a number.`)
      }
    })
  }
  if (Array.isArray(data.datasets)) {
    data.datasets.forEach((ds, i) => {
      if (isRecord(ds) && ds.label !== undefined && typeof ds.label !== 'string') {
        throw new ChartSpecError(`${base}.datasets[${i}].label must be text.`)
      }
    })
  }
}

/** Axis and legend text longer than this crowds the plot out of the chart area. */
const MAX_CATEGORY_LABEL = 80
const MAX_SERIES_NAME = 100

function boundLabel(text: string, max: number): string {
  const chars = Array.from(text)
  return chars.length > max ? `${chars.slice(0, max - 1).join('')}…` : text
}

export interface NativeChartStyle {
  /** Shown above the plot; omitted when it would repeat the slide title. */
  title?: string
  colors: string[]
  textColor: string
  mutedColor: string
}

/**
 * Values below 1000 in General, which prints each with the decimals it has,
 * and larger ones grouped: "1,200", "5,000,000" and "980.5" in one series.
 * "#,##0.##" would print the integers as "1,200.".
 */
const GROUPED_OR_GENERAL = '[>=1000]#,##0;[<=-1000]-#,##0;General'

/** Decimal places `v` carries, ignoring binary noise such as 0.1 + 0.2. */
function decimals(v: number): number {
  const text = String(Number(v.toPrecision(12)))
  if (text.includes('e')) return 0
  return text.includes('.') ? text.length - text.indexOf('.') - 1 : 0
}

/** Excel number formats for the value labels and the value axis. */
function valueFormats(values: number[]): { label: string; axis: string } {
  const fractional = values.filter(v => !Number.isInteger(v))
  let label = '#,##0'
  if (fractional.some(v => Math.abs(v) >= 1000)) {
    // Grouping and General cannot be combined, so every label gets the same decimals.
    const places = Math.min(Math.max(...fractional.map(decimals), 1), 2)
    label = `#,##0.${'0'.repeat(places)}`
  } else if (fractional.length > 0) {
    label = GROUPED_OR_GENERAL
  }
  // PowerPoint picks fractional axis steps for small ranges, which an integer
  // format would print as repeated labels; grouping only matters for large values.
  const axis = values.some(v => Math.abs(v) >= 1000) ? '#,##0' : 'General'
  return { label, axis }
}

/** Arguments for pptxgenjs `slide.addChart(type, data, options)`. */
export function nativeChartArgs(
  chart: NativeChart,
  style: NativeChartStyle,
  pptx: Pick<PptxDeck, 'charts'>
): { type: PptxGenJS.CHART_NAME; data: unknown[]; options: Record<string, unknown> } {
  const c = pptx.charts ?? {}
  const type =
    chart.type === 'line'
      ? (c.LINE ?? 'line')
      : chart.type === 'area' || chart.type === 'stackedArea'
        ? (c.AREA ?? 'area')
        : chart.type === 'pie'
          ? (c.PIE ?? 'pie')
          : chart.type === 'doughnut'
            ? (c.DOUGHNUT ?? 'doughnut')
            : (c.BAR ?? 'bar')
  const slices = SLICE_TYPES.has(chart.type)
  const stacked = chart.type === 'stackedBar' || chart.type === 'stackedArea'
  const barLike = ['bar', 'horizontalBar', 'stackedBar'].includes(chart.type)
  const labelled =
    !slices &&
    (barLike || chart.type === 'line') &&
    chart.series.every(s => s.values.length <= MAX_LABELLED_POINTS)
  const values = chart.series.flatMap(s => s.values).filter((v): v is number => v !== null)
  const format = valueFormats(values)
  const options: Record<string, unknown> = {
    barDir: chart.type === 'horizontalBar' ? 'bar' : 'col',
    // pptxgenjs colors each bar of a lone series differently when given
    // several colors, which reads as a legend that is not there.
    chartColors: barLike && chart.series.length === 1 ? style.colors.slice(0, 1) : style.colors,
    showTitle: Boolean(style.title),
    title: style.title ?? '',
    titleColor: style.textColor,
    titleFontFace: PPTX_FONT_FACE,
    titleFontSize: 16,
    // A single-series bar or line needs no key; a pie always does, because
    // its categories appear nowhere else.
    showLegend: slices || chart.series.length > 1,
    legendPos: slices ? 'r' : 'b',
    legendColor: style.textColor,
    legendFontFace: PPTX_FONT_FACE,
    legendFontSize: 12,
    catAxisLabelColor: style.mutedColor,
    catAxisLabelFontFace: PPTX_FONT_FACE,
    valAxisLabelColor: style.mutedColor,
    valAxisLabelFontFace: PPTX_FONT_FACE,
    valAxisLabelFormatCode: format.axis,
    dataLabelFontFace: PPTX_FONT_FACE,
    dataLabelFontSize: 11,
    dataLabelColor: style.textColor,
  }
  if (stacked) options.barGrouping = 'stacked'
  if (!slices) {
    // A missing value is a gap in the line, not a straight segment drawn across it.
    options.displayBlanksAs = 'gap'
  }
  if (chart.type !== 'line' && !slices) {
    // A bar or area is read by its length, so the value axis starts at zero, as
    // clerum__generate_chart draws it; PowerPoint would otherwise start near the
    // smallest value. An all-zero chart keeps an automatic maximum.
    if (values.every(v => v >= 0)) options.valAxisMinVal = 0
    else if (values.every(v => v <= 0)) options.valAxisMaxVal = 0
  }
  if (chart.type === 'horizontalBar') {
    // The first category on top, as a ranked list reads, with the value axis
    // and its labels kept at the bottom and the category names on the left.
    options.catAxisOrientation = 'maxMin'
    options.catAxisCrossesAt = 'max'
    options.valAxisLabelPos = 'nextTo'
    options.catAxisLabelPos = 'low'
  }
  if (slices) {
    options.showPercent = true
    options.showValue = false
    // Outside the slice, where the text color reads against the background;
    // a doughnut has no such position, so its labels are white on the ring.
    if (chart.type === 'pie') options.dataLabelPosition = 'outEnd'
    else options.dataLabelColor = 'FFFFFF'
  } else if (labelled) {
    options.showValue = true
    options.dataLabelFormatCode = format.label
    if (barLike && !stacked) options.dataLabelPosition = 'outEnd'
    if (chart.type === 'line') options.dataLabelPosition = 't'
  }
  const data = chart.series.map(s => ({ name: s.name, labels: chart.labels, values: s.values }))
  return { type, data, options }
}