sim:chart page fence: ECharts SSR to themed inline SVG; shared option builder

Author: Sg312

apps/sim/app/workspace/[workspaceId]/files/components/file-viewer/chart-preview.tsx

@@ -4,6 +4,7 @@ import { memo, useEffect, useMemo, useRef, useState } from 'react'
 import { getErrorMessage } from '@sim/utils/errors'
 import type { EChartsOption } from 'echarts'
 import { useTheme } from 'next-themes'
+import { buildChartRenderOption } from '@/lib/charts/option'
 import { getColumnId } from '@/lib/table/column-keys'
 import { useTable, useTableRowsSample } from '@/hooks/queries/tables'
 import { PreviewLoadingFrame } from './preview-shared'
@@ -172,80 +173,8 @@ export function shapeTableRows(
   return out
 }
 
-/**
- * Merges the resolved rows into the ECharts option as `dataset.source`. A spec
- * whose option already carries a dataset keeps it (fully self-contained static
- * charts); the file-level `title` fills in only when the option has none.
- */
 function buildOption(spec: ChartSpec, rows: Array<Record<string, unknown>> | null): EChartsOption {
-  const option = structuredClone(spec.option)
-  if (rows && rows.length > 0) {
-    // The resolved rows become the FIRST dataset (id "table", datasetIndex 0).
-    // Spec-declared datasets follow it, so filter/sort transform datasets can
-    // derive from the injected rows (transforms default to fromDatasetIndex 0,
-    // or name it explicitly with fromDatasetId: "table").
-    const injected = { id: 'table', source: rows }
-    if (option.dataset === undefined) {
-      option.dataset = injected
-    } else if (Array.isArray(option.dataset)) {
-      option.dataset = [injected, ...option.dataset]
-    } else {
-      option.dataset = [injected, option.dataset]
-    }
-  }
-  if (option.backgroundColor === undefined) {
-    option.backgroundColor = 'transparent'
-  }
-  if (spec.title && option.title === undefined) {
-    option.title = { text: spec.title }
-  }
-  // Chrome layout is Sim-owned, content is spec-owned. Models reliably
-  // produce colliding title/legend placements, so the renderer pins the
-  // title top-left and the legend top-right on one chrome row (scrollable
-  // when long), overriding any spec positions — the same split the pptx
-  // renderer makes between slide chrome and slide content.
-  const hasTitle = option.title !== null && typeof option.title === 'object'
-  if (hasTitle) {
-    const titles = Array.isArray(option.title) ? option.title : [option.title]
-    const primary = titles[0]
-    if (primary !== null && typeof primary === 'object') {
-      const t = primary as Record<string, unknown>
-      t.left = 0
-      t.top = 0
-      t.right = undefined
-      t.bottom = undefined
-    }
-    option.title = titles[0]
-  }
-  let hasLegend = false
-  if (option.legend !== null && typeof option.legend === 'object') {
-    const legends = Array.isArray(option.legend) ? option.legend : [option.legend]
-    for (const entry of legends) {
-      if (entry === null || typeof entry !== 'object') continue
-      hasLegend = true
-      const l = entry as Record<string, unknown>
-      l.top = 2
-      l.right = 0
-      l.left = undefined
-      l.bottom = undefined
-      if (l.type === undefined) l.type = 'scroll'
-    }
-  }
-  // Reserve a chrome row above the plot. Fill only what the spec left unset
-  // inside grid — axis-name insets remain the spec's call.
-  const chromeTop = hasTitle || hasLegend ? 48 : 16
-  if (option.grid === undefined) {
-    option.grid = { top: chromeTop, left: 12, right: 12, bottom: 12, containLabel: true }
-  } else if (
-    option.grid !== null &&
-    typeof option.grid === 'object' &&
-    !Array.isArray(option.grid)
-  ) {
-    const g = option.grid as Record<string, unknown>
-    if (g.top === undefined) g.top = chromeTop
-    if (g.containLabel === undefined) g.containLabel = true
-  }
-  return option as EChartsOption
+  return buildChartRenderOption({ title: spec.title, option: spec.option, rows }) as EChartsOption
 }
 
 function ChartErrorPanel({ message, content }: { message: string; content: string }) {

apps/sim/lib/charts/option.ts

@@ -0,0 +1,87 @@
+/**
+ * Shared ECharts option assembly for Sim chart surfaces — the `.chart` file
+ * viewer (client) and the sim-page `sim:chart` SSR renderer (server). Pure:
+ * no React, no echarts import, JSON-in/JSON-out.
+ *
+ * Chrome layout is Sim-owned, content is spec-owned. Models reliably produce
+ * colliding title/legend placements, so the renderer pins the title top-left
+ * and the legend top-right on one chrome row (scrollable when long),
+ * overriding any spec positions — the same split the pptx renderer makes
+ * between slide chrome and slide content.
+ */
+
+export interface ChartRenderInput {
+  title?: string
+  option: Record<string, unknown>
+  rows?: Array<Record<string, unknown>> | null
+}
+
+export function buildChartRenderOption({
+  title,
+  option: specOption,
+  rows,
+}: ChartRenderInput): Record<string, unknown> {
+  const option = structuredClone(specOption)
+  if (rows && rows.length > 0) {
+    // The resolved rows become the FIRST dataset (id "table", datasetIndex 0).
+    // Spec-declared datasets follow it, so filter/sort transform datasets can
+    // derive from the injected rows (transforms default to fromDatasetIndex 0,
+    // or name it explicitly with fromDatasetId: "table").
+    const injected = { id: 'table', source: rows }
+    if (option.dataset === undefined) {
+      option.dataset = injected
+    } else if (Array.isArray(option.dataset)) {
+      option.dataset = [injected, ...option.dataset]
+    } else {
+      option.dataset = [injected, option.dataset]
+    }
+  }
+  if (option.backgroundColor === undefined) {
+    option.backgroundColor = 'transparent'
+  }
+  if (title && option.title === undefined) {
+    option.title = { text: title }
+  }
+  const hasTitle = option.title !== null && typeof option.title === 'object'
+  if (hasTitle) {
+    const titles = Array.isArray(option.title) ? option.title : [option.title]
+    const primary = titles[0]
+    if (primary !== null && typeof primary === 'object') {
+      const t = primary as Record<string, unknown>
+      t.left = 0
+      t.top = 0
+      t.right = undefined
+      t.bottom = undefined
+    }
+    option.title = titles[0]
+  }
+  let hasLegend = false
+  if (option.legend !== null && typeof option.legend === 'object') {
+    const legends = Array.isArray(option.legend) ? option.legend : [option.legend]
+    for (const entry of legends) {
+      if (entry === null || typeof entry !== 'object') continue
+      hasLegend = true
+      const l = entry as Record<string, unknown>
+      l.top = 2
+      l.right = 0
+      l.left = undefined
+      l.bottom = undefined
+      if (l.type === undefined) l.type = 'scroll'
+    }
+  }
+  // Reserve a chrome row above the plot. Fill only what the spec left unset
+  // inside grid — axis-name insets remain the spec's call.
+  const chromeTop = hasTitle || hasLegend ? 48 : 16
+  if (option.grid === undefined) {
+    option.grid = { top: chromeTop, left: 12, right: 12, bottom: 12, containLabel: true }
+  } else if (
+    option.grid !== null &&
+    typeof option.grid === 'object' &&
+    !Array.isArray(option.grid)
+  ) {
+    const g = option.grid as Record<string, unknown>
+    if (g.top === undefined) g.top = chromeTop
+    if (g.containLabel === undefined) g.containLabel = true
+  }
+  return option
+}

apps/sim/lib/workspace-files/artifact-stylesheet.ts

@@ -390,6 +390,27 @@ figcaption { font-size: 0.875em; line-height: 1.4285714; color: var(--text-prima
 .faq details > :not(summary) { padding: 0 1rem; }
 .faq details > :last-child { padding-bottom: 0.9rem; margin-bottom: 0; }
 
+/* sim:chart — SSR'd ECharts SVGs, one per theme, swapped by the same
+   data-theme stamp the rest of the sheet keys on. The SVG carries a fixed
+   viewport; scale it to the text column. */
+.sim-chart { margin: 1.5rem 0; }
+.sim-chart svg { max-width: 100%; height: auto; display: block; margin: 0 auto; }
+.sim-chart .sim-chart-dark { display: none; }
+.sim-chart-placeholder {
+  border: 1px dashed var(--border);
+  border-radius: 0.75rem;
+  padding: 2.5rem 1rem;
+  text-align: center;
+  color: var(--text-muted);
+  font-size: var(--text-sm);
+}
+@media (prefers-color-scheme: dark) {
+  :root:not([data-theme="light"]) .sim-chart .sim-chart-light { display: none; }
+  :root:not([data-theme="light"]) .sim-chart .sim-chart-dark { display: block; }
+}
+[data-theme="dark"] .sim-chart .sim-chart-light { display: none; }
+[data-theme="dark"] .sim-chart .sim-chart-dark { display: block; }
+
 /* The fumadocs callout: a rounded-xl bordered card at 14px with a rounded
    2px color bar down the start edge (the docs strip its shadow). */
 .callout {

apps/sim/lib/workspace-files/page-chart-ssr.server.test.ts

@@ -0,0 +1,72 @@
+/**
+ * @vitest-environment node
+ */
+import { describe, expect, it } from 'vitest'
+// Side-effect import: registers the SSR sim:chart renderer with page-compile.
+import '@/lib/workspace-files/page-chart-ssr.server'
+import { compileSimPage } from '@/lib/workspace-files/page-compile'
+
+function page(body: string): string {
+  return `---\ntitle: Test\n---\n\n${body}\n`
+}
+
+describe('sim:chart SSR rendering', () => {
+  it('renders a chart fence to themed inline SVGs', () => {
+    const source = page(
+      [
+        '```sim:chart Revenue by month',
+        JSON.stringify({
+          height: 240,
+          option: {
+            xAxis: { type: 'category', data: ['Jan', 'Feb'] },
+            yAxis: { type: 'value' },
+            series: [{ type: 'bar', data: [3, 5] }],
+          },
+        }),
+        '```',
+      ].join('\n')
+    )
+    const diagnostics: string[] = []
+    const html = compileSimPage(source, { diagnostics })
+    expect(diagnostics).toEqual([])
+    expect(html).toContain('<figure class="sim-chart">')
+    expect(html).toContain('sim-chart-light')
+    expect(html).toContain('sim-chart-dark')
+    expect(html).toContain('<svg')
+    expect(html).toContain('Revenue by month')
+  })
+
+  it('injects rows as the dataset for encode-based options', () => {
+    const source = page(
+      [
+        '```sim:chart',
+        JSON.stringify({
+          rows: [
+            { month: 'Jan', revenue: 10 },
+            { month: 'Feb', revenue: 20 },
+          ],
+          option: {
+            xAxis: { type: 'category' },
+            yAxis: { type: 'value' },
+            series: [{ type: 'bar', encode: { x: 'month', y: 'revenue' } }],
+          },
+        }),
+        '```',
+      ].join('\n')
+    )
+    const diagnostics: string[] = []
+    const html = compileSimPage(source, { diagnostics })
+    expect(diagnostics).toEqual([])
+    expect(html).toContain('<svg')
+    expect(html).toContain('Feb')
+  })
+
+  it('reports a diagnostic for a payload without an option object', () => {
+    const source = page(['```sim:chart', '{"rows": []}', '```'].join('\n'))
+    const diagnostics: string[] = []
+    const html = compileSimPage(source, { diagnostics })
+    expect(diagnostics).toHaveLength(1)
+    expect(diagnostics[0]).toContain('sim:chart block skipped')
+    expect(html).not.toContain('<figure class="sim-chart">')
+  })
+})

apps/sim/lib/workspace-files/page-chart-ssr.server.ts

@@ -0,0 +1,81 @@
+import * as echarts from 'echarts'
+import { buildChartRenderOption } from '@/lib/charts/option'
+import { registerChartFenceRenderer } from '@/lib/workspace-files/page-compile'
+
+/**
+ * Server-side `sim:chart` renderer: ECharts SSR to inline SVG, once per theme.
+ * Importing this module registers it with page-compile (side-effect module —
+ * import it from every server compile entrypoint). Pages are static documents,
+ * so the embed is a styled snapshot; the live interactive artifact remains the
+ * `.chart` file, which a page links with `[Name](sim:file/<id>)`.
+ */
+
+const CHART_SSR_WIDTH = 860
+const CHART_SSR_DEFAULT_HEIGHT = 420
+const CHART_SSR_MIN_HEIGHT = 200
+const CHART_SSR_MAX_HEIGHT = 800
+
+interface ChartFencePayload {
+  option: Record<string, unknown>
+  rows?: Array<Record<string, unknown>>
+  height?: number
+}
+
+function parsePayload(payload: unknown): ChartFencePayload | null {
+  if (payload === null || typeof payload !== 'object' || Array.isArray(payload)) return null
+  const doc = payload as Record<string, unknown>
+  if (doc.option === null || typeof doc.option !== 'object' || Array.isArray(doc.option)) {
+    return null
+  }
+  if (doc.rows !== undefined && !Array.isArray(doc.rows)) return null
+  return doc as unknown as ChartFencePayload
+}
+
+function renderSvg(
+  option: Record<string, unknown>,
+  theme: 'light' | 'dark',
+  height: number
+): string {
+  const chart = echarts.init(null, theme === 'dark' ? 'dark' : undefined, {
+    renderer: 'svg',
+    ssr: true,
+    width: CHART_SSR_WIDTH,
+    height,
+  })
+  try {
+    chart.setOption(option as Parameters<typeof chart.setOption>[0])
+    return chart.renderToSVGString()
+  } finally {
+    chart.dispose()
+  }
+}
+
+function renderChartFence(payload: unknown, caption: string): string | null {
+  const parsed = parsePayload(payload)
+  if (!parsed) return null
+  const height = Math.min(
+    Math.max(Math.round(parsed.height ?? CHART_SSR_DEFAULT_HEIGHT), CHART_SSR_MIN_HEIGHT),
+    CHART_SSR_MAX_HEIGHT
+  )
+  const option = buildChartRenderOption({ option: parsed.option, rows: parsed.rows ?? null })
+  let light: string
+  let dark: string
+  try {
+    light = renderSvg(option, 'light', height)
+    dark = renderSvg(option, 'dark', height)
+  } catch {
+    return null
+  }
+  const figcaption = caption ? `<figcaption>${escapeHtml(caption)}</figcaption>` : ''
+  return `<figure class="sim-chart"><div class="sim-chart-light">${light}</div><div class="sim-chart-dark">${dark}</div>${figcaption}</figure>`
+}
+
+function escapeHtml(text: string): string {
+  return text
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+}
+
+registerChartFenceRenderer(renderChartFence)