@svgrid/grid 3.0.2 → 3.0.4

package/src/chart-export-pdf.ts

@@ -0,0 +1,207 @@
+/**
+ * PDF and print for a rendered chart, with no PDF library.
+ *
+ * A one-page PDF is a short text file with one binary blob in it, so the
+ * writer here is the whole format we need: a catalog, a page, a Helvetica
+ * font, one image XObject and a content stream that places the text and the
+ * image. The chart is rasterised through the existing PNG path and re-encoded
+ * as JPEG, which the PDF embeds as-is under `/DCTDecode`; nothing needs zlib.
+ * JPEG has no alpha, so the chart background is always painted.
+ *
+ * Print opens a window with the standalone SVG and calls `print()`.
+ */
+import { chartToPngBlob, chartToSvgString, type ChartExportOptions } from './chart-export'
+
+/** Options for the PDF: page, orientation, the text around the chart. */
+export type ChartPdfOptions = ChartExportOptions & {
+  /** Paper size. Default A4. */
+  page?: 'A4' | 'Letter'
+  /** Default: whichever fits the chart's aspect ratio better. */
+  orientation?: 'portrait' | 'landscape'
+  title?: string
+  subtitle?: string
+  caption?: string
+  /** JPEG quality, 0..1. Default 0.92. */
+  quality?: number
+}
+
+const PAGES: Record<'A4' | 'Letter', [number, number]> = { A4: [595.28, 841.89], Letter: [612, 792] }
+
+/** Latin-1 bytes of a string; anything outside it becomes `?`. */
+function latin1(s: string): Uint8Array {
+  const out = new Uint8Array(s.length)
+  for (let i = 0; i < s.length; i += 1) {
+    const c = s.charCodeAt(i)
+    out[i] = c < 256 ? c : 63
+  }
+  return out
+}
+
+/** A PDF string literal: parentheses and backslashes escaped. */
+function pdfText(s: string): string {
+  return '(' + s.replace(/[\\()]/g, (m) => '\\' + m).replace(/[\r\n]+/g, ' ') + ')'
+}
+
+/** Roughly how wide Helvetica text is at a size, for fitting a line. */
+function textWidth(s: string, size: number): number {
+  return s.length * size * 0.5
+}
+
+/** Re-encode a PNG blob as JPEG on a painted background. */
+function pngToJpeg(png: Blob, background: string, quality: number): Promise<{ bytes: Uint8Array; width: number; height: number }> {
+  return new Promise((resolve, reject) => {
+    const url = URL.createObjectURL(png)
+    const img = new Image()
+    img.onload = () => {
+      const canvas = document.createElement('canvas')
+      canvas.width = img.naturalWidth || img.width
+      canvas.height = img.naturalHeight || img.height
+      const ctx = canvas.getContext('2d')
+      if (!ctx) { URL.revokeObjectURL(url); reject(new Error('canvas 2d context unavailable')); return }
+      ctx.fillStyle = background
+      ctx.fillRect(0, 0, canvas.width, canvas.height)
+      ctx.drawImage(img, 0, 0)
+      URL.revokeObjectURL(url)
+      canvas.toBlob(
+        (blob) => {
+          if (!blob) { reject(new Error('toBlob failed')); return }
+          blob.arrayBuffer().then((buf) => resolve({ bytes: new Uint8Array(buf), width: canvas.width, height: canvas.height }), reject)
+        },
+        'image/jpeg',
+        quality,
+      )
+    }
+    img.onerror = () => { URL.revokeObjectURL(url); reject(new Error('failed to decode chart PNG')) }
+    img.src = url
+  })
+}
+
+/**
+ * Assemble a one-page PDF from a JPEG and the text around it. Exported for
+ * tests and for callers that already have a JPEG; `chartToPdfBlob` is the
+ * one that starts from a chart element.
+ */
+export function buildChartPdf(
+  jpeg: { bytes: Uint8Array; width: number; height: number },
+  opts: Pick<ChartPdfOptions, 'page' | 'orientation' | 'title' | 'subtitle' | 'caption'> = {},
+): Uint8Array {
+  const [pw0, ph0] = PAGES[opts.page ?? 'A4']
+  const landscape = opts.orientation ? opts.orientation === 'landscape' : jpeg.width / jpeg.height > pw0 / ph0
+  const pw = landscape ? ph0 : pw0
+  const ph = landscape ? pw0 : ph0
+  const margin = 40
+  const title = (opts.title ?? '').trim()
+  const subtitle = (opts.subtitle ?? '').trim()
+  const caption = (opts.caption ?? '').trim()
+
+  // Text block at the top, image below it, caption at the foot.
+  let y = ph - margin
+  const content: string[] = []
+  const line = (text: string, size: number, gray: number) => {
+    y -= size + 4
+    content.push(`BT /F1 ${size} Tf ${gray} g ${margin} ${y.toFixed(2)} Td ${pdfText(text)} Tj ET`)
+  }
+  if (title) line(title, 16, 0)
+  if (subtitle) line(subtitle, 11, 0.4)
+  if (title || subtitle) y -= 8
+  const footer = caption ? 20 : 0
+  const availW = pw - margin * 2
+  const availH = y - margin - footer
+  const scale = Math.min(availW / jpeg.width, availH / jpeg.height)
+  const iw = jpeg.width * scale
+  const ih = jpeg.height * scale
+  const ix = margin + (availW - iw) / 2
+  const iy = y - ih
+  content.push(`q ${iw.toFixed(2)} 0 0 ${ih.toFixed(2)} ${ix.toFixed(2)} ${iy.toFixed(2)} cm /Im1 Do Q`)
+  if (caption) {
+    const size = 9
+    const text = textWidth(caption, size) > availW ? caption.slice(0, Math.floor(availW / (size * 0.5)) - 3) + '...' : caption
+    content.push(`BT /F1 ${size} Tf 0.4 g ${margin} ${(margin - 4).toFixed(2)} Td ${pdfText(text)} Tj ET`)
+  }
+  const stream = content.join('\n')
+
+  const objects: Array<Uint8Array | string> = []
+  const offsets: number[] = []
+  let length = 0
+  const push = (part: Uint8Array | string) => {
+    objects.push(part)
+    length += typeof part === 'string' ? part.length : part.length
+  }
+  push('%PDF-1.4\n%âãÏÓ\n')
+  const obj = (n: number, body: string, bin?: Uint8Array) => {
+    offsets[n] = length
+    push(`${n} 0 obj\n${body}\n`)
+    if (bin) {
+      push('stream\n')
+      push(bin)
+      push('\nendstream\n')
+    }
+    push('endobj\n')
+  }
+  obj(1, '<< /Type /Catalog /Pages 2 0 R >>')
+  obj(2, '<< /Type /Pages /Kids [3 0 R] /Count 1 >>')
+  obj(3, `<< /Type /Page /Parent 2 0 R /MediaBox [0 0 ${pw.toFixed(2)} ${ph.toFixed(2)}] /Resources << /XObject << /Im1 4 0 R >> /Font << /F1 5 0 R >> >> /Contents 6 0 R >>`)
+  obj(4, `<< /Type /XObject /Subtype /Image /Width ${jpeg.width} /Height ${jpeg.height} /ColorSpace /DeviceRGB /BitsPerComponent 8 /Filter /DCTDecode /Length ${jpeg.bytes.length} >>`, jpeg.bytes)
+  obj(5, '<< /Type /Font /Subtype /Type1 /BaseFont /Helvetica /Encoding /WinAnsiEncoding >>')
+  obj(6, `<< /Length ${stream.length} >>`, latin1(stream))
+  const xref = length
+  push(`xref\n0 7\n0000000000 65535 f \n`)
+  for (let n = 1; n <= 6; n += 1) push(`${String(offsets[n]).padStart(10, '0')} 00000 n \n`)
+  push(`trailer\n<< /Size 7 /Root 1 0 R >>\nstartxref\n${xref}\n%%EOF\n`)
+
+  const out = new Uint8Array(new ArrayBuffer(length))
+  let at = 0
+  for (const part of objects) {
+    const bytes = typeof part === 'string' ? latin1(part) : part
+    out.set(bytes, at)
+    at += bytes.length
+  }
+  return out
+}
+
+/** The chart as a one-page PDF `Blob`. */
+export async function chartToPdfBlob(source: SVGSVGElement | HTMLElement, options: ChartPdfOptions = {}): Promise<Blob> {
+  const svg = source instanceof SVGSVGElement ? source : (source.querySelector('svg.sv-grid-chart-svg') ?? source.querySelector('svg'))
+  const background = options.background ?? (svg ? getComputedStyle(svg).getPropertyValue('--sg-bg').trim() || '#ffffff' : '#ffffff')
+  const png = await chartToPngBlob(source, { ...options, background, scale: options.scale ?? 2 })
+  const jpeg = await pngToJpeg(png, background, options.quality ?? 0.92)
+  const bytes = buildChartPdf(jpeg, options)
+  return new Blob([bytes.buffer as ArrayBuffer], { type: 'application/pdf' })
+}
+
+/** Download the chart as a `.pdf` file. */
+export async function downloadChartPdf(source: SVGSVGElement | HTMLElement, filename = 'chart.pdf', options: ChartPdfOptions = {}): Promise<void> {
+  const blob = await chartToPdfBlob(source, options)
+  const url = URL.createObjectURL(blob)
+  const a = document.createElement('a')
+  a.href = url
+  a.download = filename
+  document.body.appendChild(a)
+  a.click()
+  a.remove()
+  setTimeout(() => URL.revokeObjectURL(url), 1000)
+}
+
+/**
+ * Print the chart: a new window with the standalone SVG (and the title
+ * above it), sized to the page, that opens the print dialog once it has
+ * drawn. Returns false when the window was blocked.
+ */
+export function printChart(source: SVGSVGElement | HTMLElement, options: ChartExportOptions & { title?: string } = {}): boolean {
+  const svg = chartToSvgString(source, options)
+  const win = window.open('', '_blank', 'width=900,height=700')
+  if (!win) return false
+  const esc = (s: string) => s.replace(/[&<>]/g, (m) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;' })[m]!)
+  win.document.write(
+    `<!doctype html><html><head><meta charset="utf-8"><title>${esc(options.title ?? 'Chart')}</title>` +
+      `<style>body{margin:24px;font-family:system-ui,sans-serif}h1{font-size:16px;margin:0 0 12px}svg{max-width:100%;height:auto}@page{margin:12mm}</style></head><body>` +
+      (options.title ? `<h1>${esc(options.title)}</h1>` : '') +
+      svg +
+      `</body></html>`,
+  )
+  win.document.close()
+  const go = () => { win.focus(); win.print() }
+  if (win.document.readyState === 'complete') setTimeout(go, 50)
+  else win.addEventListener('load', () => setTimeout(go, 50))
+  return true
+}

package/src/chart-export.test.ts

@@ -372,6 +372,20 @@ describe('downloadChartPng', () => {
   })
 })
 
+describe('chartSpecToCsv: gaps', () => {
+  it('writes a NaN or null value as an empty cell, not the word NaN', () => {
+    const csv = chartSpecToCsv({
+      type: 'line',
+      categories: ['Jan', 'Feb', 'Mar'],
+      series: [
+        { label: 'Actual', values: [10, Number.NaN, 12] },
+        { label: 'Forecast', values: [null as unknown as number, 11, Number.NaN] },
+      ],
+    })
+    expect(csv.split('\n')).toEqual(['Category,Actual,Forecast', 'Jan,10,', 'Feb,,11', 'Mar,12,'])
+  })
+})
+
 describe('chartSpecToCsv: series that carry more than one number', () => {
   it('keeps a plain series byte-identical', () => {
     const csv = chartSpecToCsv({

package/src/chart-export.ts

@@ -170,7 +170,9 @@ export async function downloadChartPng(
 }
 
 const csvCell = (v: unknown): string => {
-  const s = v == null ? '' : String(v)
+  // A gap is an empty cell: `null` already was, and a NaN gap (the way a
+  // forecast series marks the months before it starts) wrote the word "NaN".
+  const s = v == null || (typeof v === 'number' && !Number.isFinite(v)) ? '' : String(v)
   return /[",\n]/.test(s) ? `"${s.replace(/"/g, '""')}"` : s
 }
 
@@ -180,7 +182,8 @@ const csvCell = (v: unknown): string => {
  *
  * A series that carries more than one number per category widens instead of
  * losing them. `ohlc` becomes four columns, `boxes` five plus its outliers,
- * `errors` two. This used to write `values` and nothing else, which quietly
+ * `errors` two, `lowValues` a low / high pair, `targets` a value / target
+ * pair. This used to write `values` and nothing else, which quietly
  * made "Export CSV" on a candlestick chart hand back the closing prices only -
  * the screen-reader table was given the four real numbers on purpose and the
  * export, which is what people actually take away, was not.
@@ -213,9 +216,11 @@ export function chartSpecToCsv(spec: ChartSpec): string {
   // bare label, so an existing export is byte-identical.
   const header: string[] = ['Category']
   for (const s of series) {
-    if (s.ohlc) header.push(`${s.label} Open`, `${s.label} High`, `${s.label} Low`, `${s.label} Close`)
+    if (s.ohlc) header.push(`${s.label} Open`, `${s.label} High`, `${s.label} Low`, `${s.label} Close`, ...(s.volumes ? [`${s.label} Volume`] : []))
     else if (s.boxes) header.push(`${s.label} Min`, `${s.label} Q1`, `${s.label} Median`, `${s.label} Q3`, `${s.label} Max`, `${s.label} Outliers`)
     else if (s.errors) header.push(s.label, `${s.label} Low`, `${s.label} High`)
+    else if (s.lowValues) header.push(`${s.label} low`, `${s.label} high`)
+    else if (s.targets) header.push(s.label, `${s.label} target`)
     else header.push(s.label)
   }
 
@@ -225,6 +230,7 @@ export function chartSpecToCsv(spec: ChartSpec): string {
       if (s.ohlc) {
         const k = s.ohlc[i]
         cells.push(k?.o ?? '', k?.h ?? '', k?.l ?? '', k?.c ?? '')
+        if (s.volumes) cells.push(s.volumes[i] ?? '')
       } else if (s.boxes) {
         const b = s.boxes[i]
         // Outliers are a list inside one cell; csvCell quotes it.
@@ -235,6 +241,10 @@ export function chartSpecToCsv(spec: ChartSpec): string {
         const lo = e == null ? '' : typeof e === 'number' ? (v ?? 0) - Math.abs(e) : Math.min(e.lo, e.hi)
         const hi = e == null ? '' : typeof e === 'number' ? (v ?? 0) + Math.abs(e) : Math.max(e.lo, e.hi)
         cells.push(v ?? '', lo, hi)
+      } else if (s.lowValues) {
+        cells.push(s.lowValues[i] ?? '', s.values[i] ?? '')
+      } else if (s.targets) {
+        cells.push(s.values[i] ?? '', s.targets[i] ?? '')
       } else {
         cells.push(s.values[i] ?? '')
       }

package/src/chart-financial.ts

@@ -0,0 +1,208 @@
+/**
+ * Price-chart helpers: candle transforms, calendar resampling and the
+ * row-to-candlestick adapter. Indicators live in chart-indicators. DOM-free.
+ */
+import type { ChartSeries, ChartSpec, OhlcBar, SeriesOverlay } from './chart-types'
+import { bucketStart, type ChartTimeBucket } from './chart-stats'
+import type { ChartIndicatorSpec } from './chart-indicators'
+
+/**
+ * Heikin-Ashi ("average bar") candles from ordinary OHLC bars. Each close is
+ * the mean of the four prices, each open the midpoint of the previous
+ * Heikin-Ashi body, and the high / low stretch to include both. Runs of one
+ * colour then read as trends, at the cost of the true open and close.
+ * `null` bars (gaps) stay null and reset the chain.
+ */
+export function heikinAshi(bars: ReadonlyArray<OhlcBar | null>): Array<OhlcBar | null> {
+  const out: Array<OhlcBar | null> = new Array(bars.length)
+  let prev: OhlcBar | null = null
+  for (let i = 0; i < bars.length; i += 1) {
+    const b = bars[i]
+    if (!b || ![b.o, b.h, b.l, b.c].every(Number.isFinite)) {
+      out[i] = null
+      prev = null
+      continue
+    }
+    const c = (b.o + b.h + b.l + b.c) / 4
+    const o = prev ? (prev.o + prev.c) / 2 : (b.o + b.c) / 2
+    const ha: OhlcBar = { o, c, h: Math.max(b.h, o, c), l: Math.min(b.l, o, c) }
+    out[i] = ha
+    prev = ha
+  }
+  return out
+}
+
+/**
+ * Roll daily (or finer) bars up to a coarser calendar bucket: the first
+ * open, the highest high, the lowest low, the last close, the summed volume.
+ * Categories are ISO dates and come back as the bucket starts (`bucketStart`),
+ * sorted; bars whose date does not parse are dropped. Pass `volumes` to get
+ * them summed alongside.
+ */
+export function resampleOhlc(
+  categories: ReadonlyArray<string>,
+  ohlc: ReadonlyArray<OhlcBar | null>,
+  opts: { bucket: ChartTimeBucket; volumes?: ReadonlyArray<number> },
+): { categories: string[]; ohlc: Array<OhlcBar | null>; volumes?: number[] } {
+  const groups = new Map<string, { bar: OhlcBar | null; vol: number; first: number; last: number }>()
+  const order: Array<[string, number]> = []
+  for (let i = 0; i < categories.length; i += 1) {
+    const t = Date.parse(categories[i]!)
+    if (!Number.isFinite(t)) continue
+    const key = bucketStart(t, opts.bucket)
+    if (!key) continue
+    let g = groups.get(key)
+    if (!g) {
+      g = { bar: null, vol: 0, first: Infinity, last: -Infinity }
+      groups.set(key, g)
+      order.push([key, Date.parse(key)])
+    }
+    const b = ohlc[i]
+    if (b) {
+      // Rows may arrive out of order: the open is the EARLIEST bar's and the
+      // close the LATEST bar's, by date, not by position.
+      if (!g.bar) g.bar = { ...b }
+      else {
+        g.bar.h = Math.max(g.bar.h, b.h)
+        g.bar.l = Math.min(g.bar.l, b.l)
+        if (t >= g.last) g.bar.c = b.c
+        if (t <= g.first) g.bar.o = b.o
+      }
+      if (t > g.last) g.last = t
+      if (t < g.first) g.first = t
+    }
+    const v = opts.volumes?.[i]
+    if (Number.isFinite(v)) g.vol += v!
+  }
+  order.sort((a, b) => a[1] - b[1])
+  const out = {
+    categories: order.map(([k]) => k),
+    ohlc: order.map(([k]) => groups.get(k)!.bar),
+    ...(opts.volumes ? { volumes: order.map(([k]) => groups.get(k)!.vol) } : {}),
+  }
+  return out
+}
+
+/** What the grid's chart panel stores for a price chart: the column ids. */
+export type OhlcColumns = { open: string | null; high: string | null; low: string | null; close: string | null; volume: string | null }
+
+/**
+ * Guess the price columns from their names: the first numeric column called
+ * open / high / low / close (or last, price) / volume. What the chart panel
+ * shows before the reader picks anything; a picked column always wins.
+ */
+export function guessOhlcColumns(
+  measures: ReadonlyArray<{ id: string; field: string; label: string }>,
+  picked?: Partial<OhlcColumns> | null,
+): OhlcColumns {
+  const guess = (re: RegExp) => measures.find((m) => re.test(m.field) || re.test(m.label))?.id ?? null
+  return {
+    open: picked?.open ?? guess(/open/i),
+    high: picked?.high ?? guess(/high/i),
+    low: picked?.low ?? guess(/low/i),
+    close: picked?.close ?? guess(/close|last|price/i),
+    volume: picked?.volume ?? guess(/vol/i),
+  }
+}
+
+/**
+ * The `rowsToDirectSpec` options for the grid panel's price chart, or null
+ * while a price column is still unpicked. `fieldOf` maps a column id to its
+ * field name; the date column is the category.
+ */
+export function ohlcDirectOptions(
+  fieldOf: (id: string | null) => string | null | undefined,
+  dateId: string | null,
+  cols: OhlcColumns,
+  extra: { bucket?: ChartTimeBucket | null; candleStyle?: ChartSpec['candleStyle'] | null },
+): { category: string; ohlc: NonNullable<Parameters<typeof import('./chart').rowsToDirectSpec>[2]['ohlc']> } | null {
+  const date = fieldOf(dateId)
+  const open = fieldOf(cols.open)
+  const high = fieldOf(cols.high)
+  const low = fieldOf(cols.low)
+  const close = fieldOf(cols.close)
+  if (!date || !open || !high || !low || !close) return null
+  const volume = fieldOf(cols.volume)
+  return {
+    category: date,
+    ohlc: {
+      open, high, low, close,
+      ...(volume ? { volume } : {}),
+      ...(extra.bucket ? { bucket: extra.bucket } : {}),
+      ...(extra.candleStyle ? { candleStyle: extra.candleStyle } : {}),
+      lastPriceLine: true,
+    },
+  }
+}
+
+/** The indicator names the grid's chart panel offers. */
+export type ChartPanelIndicator = 'volume' | 'rsi' | 'macd' | 'stochastic' | 'atr' | 'obv' | 'sma' | 'ema' | 'bb' | 'vwap'
+
+/**
+ * Split the panel's indicator list into the panes that go under the price
+ * (in order) and the one overlay that rides on it (a series carries a single
+ * `overlay`, so the first overlay kind wins).
+ */
+export function splitPanelIndicators(kinds: ReadonlyArray<ChartPanelIndicator>): { panes: ChartIndicatorSpec[]; overlay: SeriesOverlay | null } {
+  const OVERLAY: Partial<Record<ChartPanelIndicator, SeriesOverlay>> = { sma: 'sma:20', ema: 'ema:20', bb: 'bb:20:2', vwap: 'vwap' }
+  const panes: ChartIndicatorSpec[] = []
+  let overlay: SeriesOverlay | null = null
+  for (const k of kinds) {
+    const o = OVERLAY[k]
+    if (o) { overlay ??= o; continue }
+    if (k === 'volume' || k === 'rsi' || k === 'macd' || k === 'stochastic' || k === 'atr' || k === 'obv') panes.push({ kind: k })
+  }
+  return { panes, overlay }
+}
+
+/**
+ * A candlestick spec straight from rows: one bar per date (sorted), with the
+ * volume alongside when a field is named, optionally rolled up to a calendar
+ * bucket first. The x axis is ordinal-time, so weekends and holidays leave no
+ * gaps.
+ */
+export function rowsToOhlcSpec<T extends Record<string, unknown>>(
+  rows: ReadonlyArray<T>,
+  opts: {
+    date: keyof T & string
+    open: keyof T & string
+    high: keyof T & string
+    low: keyof T & string
+    close: keyof T & string
+    volume?: keyof T & string
+    bucket?: ChartTimeBucket
+    /** The series label. Default "Price". */
+    label?: string
+    type?: 'candlestick' | 'ohlc'
+    candleStyle?: ChartSpec['candleStyle']
+    lastPriceLine?: boolean
+  },
+): ChartSpec {
+  const num = (v: unknown): number => (typeof v === 'number' ? v : Number(v))
+  const sorted = rows
+    .map((r) => ({ r, t: Date.parse(String(r[opts.date])) }))
+    .filter((x) => Number.isFinite(x.t))
+    .sort((a, b) => a.t - b.t)
+  let categories = sorted.map((x) => new Date(x.t).toISOString().slice(0, 10))
+  let ohlc: Array<OhlcBar | null> = sorted.map(({ r }) => {
+    const b = { o: num(r[opts.open]), h: num(r[opts.high]), l: num(r[opts.low]), c: num(r[opts.close]) }
+    return [b.o, b.h, b.l, b.c].every(Number.isFinite) ? b : null
+  })
+  let volumes = opts.volume ? sorted.map(({ r }) => num(r[opts.volume!])) : undefined
+  if (opts.bucket) {
+    const rolled = resampleOhlc(categories, ohlc, { bucket: opts.bucket, volumes })
+    categories = rolled.categories
+    ohlc = rolled.ohlc
+    volumes = rolled.volumes
+  }
+  const label = opts.label ?? 'Price'
+  const series: ChartSeries = { label, values: ohlc.map((b) => (b ? b.c : Number.NaN)), ohlc, ...(volumes ? { volumes } : {}) }
+  return {
+    type: opts.type ?? 'candlestick',
+    categories,
+    series: [series],
+    xType: 'ordinal-time',
+    ...(opts.candleStyle ? { candleStyle: opts.candleStyle } : {}),
+    ...(opts.lastPriceLine ? { lastPriceLine: true } : {}),
+  }
+}