fix(dashboards): address review on chart annotations and embed refresh

Author: TheodoreSpeaks

apps/sim/components/charts/echarts-view.tsx

@@ -57,16 +57,14 @@ export function EChartsView({
       controllerRef.current = controller ?? null
       const next: { option: Record<string, unknown>; annotations?: ChartAnnotations } =
         JSON.parse(nextOption)
-      const parsed = applyChartTooltipDefaults(
-        next.annotations
-          ? applyChartAnnotations(
-              next.option,
-              next.annotations,
-              readChartTonePalette(chart.getDom())
-            )
-          : next.option
-      )
-      chart.setOption(controller ? controller.prepareOption(parsed) : parsed, { notMerge: true })
+      const parsed = applyChartTooltipDefaults(next.option)
+      // Annotate after the bar helpers read the option: the label series would read as a non-bar chart.
+      const rendered = next.annotations
+        ? applyChartAnnotations(parsed, next.annotations, readChartTonePalette(chart.getDom()))
+        : parsed
+      chart.setOption(controller ? controller.prepareOption(rendered) : rendered, {
+        notMerge: true,
+      })
       controller?.afterUpdate()
       rowHighlightRef.current?.()
       rowHighlightRef.current = installBarRowHighlight(chart, parsed)

apps/sim/components/dashboards/dashboard-embed.tsx

@@ -1,6 +1,6 @@
 'use client'
 
-import { type ReactNode, useId, useMemo, useState } from 'react'
+import { type ReactNode, useEffect, useId, useMemo, useRef, useState } from 'react'
 import { cn, Tooltip } from '@sim/emcn'
 import { useParams } from 'next/navigation'
 import { DashboardFeatureGate } from '@/components/dashboards/dashboard-feature-gate'
@@ -81,7 +81,9 @@ function LiveDashboardEmbed({ source, workspaceId }: LiveDashboardEmbedProps) {
 }
 
 function EmbedView({ spec, workspaceId }: EmbedViewProps) {
+  const rootRef = useRef<HTMLDivElement>(null)
   const embedId = useId()
+  const [inView, setInView] = useState(false)
   const [state, setState] = useState<DashboardTimeState>({
     range: null,
     from: null,
@@ -94,16 +96,26 @@ function EmbedView({ spec, workspaceId }: EmbedViewProps) {
     time: spec.time,
     workspaceId,
     tableIds: dashboardTableIds(spec.blocks, spec.source),
-    live: true,
+    live: inView,
   })
+  useEffect(() => {
+    const root = rootRef.current
+    if (!root) return
+    const observer = new IntersectionObserver(([entry]) => setInView(entry.isIntersecting))
+    observer.observe(root)
+    return () => observer.disconnect()
+  }, [])
   const zoomed = state.range !== null
   const { period } = time.controls
   const caption =
     period === 'custom'
       ? dashboardRangeText(time.range, time.interactions.timeZone)
       : DASHBOARD_RANGE_LABELS[period]
   return (
-    <div className='@container/dashboard relative flex flex-col gap-3 pt-8 font-season'>
+    <div
+      ref={rootRef}
+      className='@container/dashboard relative flex flex-col gap-3 pt-8 font-season'
+    >
       {spec.title && (
         <p className='pr-40 font-medium text-[var(--text-primary)] text-base'>{spec.title}</p>
       )}

apps/sim/components/dashboards/dashboard-panel.tsx

@@ -17,7 +17,7 @@ import { useDashboardInteractions } from '@/components/dashboards/dashboard-inte
 import type { QueryTableAnalyticsResponse } from '@/lib/api/contracts/table-analytics'
 import type { ChartAnnotations, ChartHighlight } from '@/lib/charts/annotations'
 import { buildChartRenderOption, horizontalBarChartHeight } from '@/lib/charts/option'
-import { isTimeSeriesOption } from '@/lib/charts/time-series'
+import { isTimeSeriesOption } from '@/lib/charts/spec'
 import {
   type DashboardDataBlock,
   type DashboardSource,

apps/sim/components/dashboards/use-dashboard-time.ts

@@ -1,6 +1,6 @@
 'use client'
 
-import { useEffect, useRef, useState } from 'react'
+import { useEffect, useEffectEvent, useRef, useState } from 'react'
 import { getErrorMessage } from '@sim/utils/errors'
 import { toRecord } from '@sim/utils/object'
 import { useIsFetching, useQueryClient } from '@tanstack/react-query'
@@ -32,7 +32,10 @@ interface UseDashboardTimeProps {
   time: DashboardTime | undefined
   workspaceId: string
   tableIds: ReadonlySet<string>
-  /** Advances relative ranges to the present every minute, so the view keeps up with new rows. */
+  /**
+   * Refreshes every minute while true and the page is visible: relative ranges advance to the
+   * present, fixed and zoomed ranges refetch in place.
+   */
   live?: boolean
 }
 
@@ -79,19 +82,20 @@ export function useDashboardTime({
     }
   }
 
-  const relative = period !== 'custom'
+  const tick = useEffectEvent(() => {
+    if (document.visibilityState !== 'visible') return
+    if (period === 'custom') void queryClient.invalidateQueries(queryFilter)
+    else setNow(Date.now())
+  })
   useEffect(() => {
-    if (!live || !relative) return
-    const tick = () => {
-      if (document.visibilityState === 'visible') setNow(Date.now())
-    }
+    if (!live) return
     const interval = setInterval(tick, LIVE_TICK_MS)
     document.addEventListener('visibilitychange', tick)
     return () => {
       clearInterval(interval)
       document.removeEventListener('visibilitychange', tick)
     }
-  }, [live, relative])
+  }, [live])
 
   const onZoom = (selected: DashboardTimeRange) => {
     setInputError(null)

apps/sim/lib/charts/annotations.ts

@@ -48,6 +48,15 @@ function verticalTop(option: Record<string, unknown>): 'start' | 'end' {
   return firstAxis(option.yAxis).inverse === true ? 'start' : 'end'
 }
 
+/** A chart annotations can draw on: a first series with no hand-written marks to collide with. */
+export function assertAnnotatable(option: Record<string, unknown>): void {
+  const series = Array.isArray(option.series) ? option.series : [option.series]
+  if (series[0] === undefined) throw new Error('Highlights and thresholds require a series')
+  const first = toRecord(series[0])
+  if (first.markArea !== undefined || first.markLine !== undefined)
+    throw new Error('Use highlights and thresholds instead of markArea or markLine on the series')
+}
+
 /**
  * Id of the empty series that carries annotation labels. ECharts draws a mark's label at the mark's
  * depth, so the marks sit under the data and their labels ride on this series above it.
@@ -77,11 +86,9 @@ export function applyChartAnnotations(
   const highlights = annotations.highlights ?? []
   const thresholds = annotations.thresholds ?? []
   if (highlights.length === 0 && thresholds.length === 0) return option
+  assertAnnotatable(option)
   const series = Array.isArray(option.series) ? option.series : [option.series]
-  if (series[0] === undefined) throw new Error('Highlights and thresholds require a series')
   const first = toRecord(series[0])
-  if (first.markArea !== undefined || first.markLine !== undefined)
-    throw new Error('Use highlights and thresholds instead of markArea or markLine on the series')
 
   const bands: Array<AnnotationMark & { from: string; to: string }> = []
   const lines: Array<AnnotationMark & { coord: Record<string, string | number> }> = []

apps/sim/lib/charts/spec.ts

@@ -5,6 +5,7 @@
  */
 
 import { getErrorMessage } from '@sim/utils/errors'
+import { toRecord } from '@sim/utils/object'
 import { getColumnId } from '@/lib/table/column-keys'
 import type { ColumnDefinition } from '@/lib/table/types'
 
@@ -270,3 +271,9 @@ export function shapeTableRows(
   }
   return out
 }
+
+/** Cartesian charts with one horizontal time axis share dashboard interactions. */
+export function isTimeSeriesOption(option: Record<string, unknown>): boolean {
+  const axes = Array.isArray(option.xAxis) ? option.xAxis : [option.xAxis]
+  return axes.length === 1 && toRecord(axes[0]).type === 'time'
+}

apps/sim/lib/charts/time-series.ts

@@ -30,12 +30,6 @@ export interface TimeSeriesInteractionOptions {
   onZoom?: (range: DashboardTimeRange) => void
 }
 
-/** Cartesian charts with one horizontal time axis share dashboard interactions. */
-export function isTimeSeriesOption(option: Record<string, unknown>): boolean {
-  const axes = Array.isArray(option.xAxis) ? option.xAxis : [option.xAxis]
-  return axes.length === 1 && toRecord(axes[0]).type === 'time'
-}
-
 /** Use ECharts' resolved encodings and colors, including transformed datasets. */
 export function readTimeSeriesTooltip(
   params: unknown,

apps/sim/lib/dashboards/spec.test.ts

@@ -237,6 +237,21 @@ describe('highlights and thresholds', () => {
     ).toBe('highlights.0.tone: Invalid option: expected one of "neutral"|"error"|"info"')
   })
 
+  it('rejects highlights or thresholds on a chart with hand-written marks', () => {
+    const marked =
+      'blocks:\n  - chart: Weekly\n    source: {groupBy: [createdAt], bucket: week, aggregate: {n: {op: count}}}\n    option: {xAxis: {type: time}, yAxis: {type: value}, series: [{type: line, markLine: {data: []}}]}\n'
+    const message = 'Use highlights and thresholds instead of markArea or markLine on the series'
+    expect(
+      parseDashboardEmbed(
+        `source: {tableId: tbl_1}\nhighlights: [{at: 2026-09-10T00:00:00Z}]\n${marked}`
+      ).error
+    ).toBe(message)
+    expect(
+      parseDashboardEmbed(`source: {tableId: tbl_1}\n${marked}    thresholds: [{value: 5}]\n`).error
+    ).toBe(message)
+    expect(parseDashboardEmbed(`source: {tableId: tbl_1}\n${marked}`).error).toBeUndefined()
+  })
+
   it('accepts thresholds on a chart with a value axis and rejects them without one', () => {
     expect(
       parseDashboardEmbed(

apps/sim/lib/dashboards/spec.ts

@@ -3,12 +3,13 @@ import { omit } from '@sim/utils/object'
 import { JSON_SCHEMA, load } from 'js-yaml'
 import { z } from 'zod'
 import {
+  assertAnnotatable,
   CHART_TONES,
   type ChartHighlight,
   type ChartThreshold,
   valueAxisKey,
 } from '@/lib/charts/annotations'
-import { parseChartSpec } from '@/lib/charts/spec'
+import { isTimeSeriesOption, parseChartSpec } from '@/lib/charts/spec'
 import {
   type DashboardTimeRange,
   parseDashboardCustomRange,
@@ -307,7 +308,8 @@ function loadBoundedYaml(content: string, maxBytes: number, tooLarge: string): u
 function validateDashboardBlocks(
   blocks: DashboardBlock[],
   defaults: DashboardSource | undefined,
-  maxBlocks: number
+  maxBlocks: number,
+  highlights: ChartHighlight[] | undefined
 ): void {
   let count = 0
   const visit = (children: DashboardBlock[], depth: number): void => {
@@ -339,6 +341,8 @@ function validateDashboardBlocks(
           if (!chart.spec) throw new Error(chart.error)
           block.option = chart.spec.option
           if (block.thresholds) valueAxisKey(block.option)
+          if (block.thresholds || (highlights && isTimeSeriesOption(block.option)))
+            assertAnnotatable(block.option)
         }
       }
     }
@@ -353,7 +357,7 @@ export function parseDashboardSpec(content: string): ParseResult<DashboardSpec>
     const parsed = dashboardSchema.safeParse(raw)
     if (!parsed.success)
       throw new Error(describeSchemaIssues(parsed.error.issues, BLOCK_KINDS).join('\n'))
-    validateDashboardBlocks(parsed.data.blocks, parsed.data.source, 48)
+    validateDashboardBlocks(parsed.data.blocks, parsed.data.source, 48, parsed.data.highlights)
     return { spec: parsed.data }
   } catch (error) {
     return { error: getErrorMessage(error, 'Invalid dashboard') }
@@ -371,7 +375,12 @@ export function parseDashboardEmbed(content: string): ParseResult<DashboardEmbed
     const parsed = dashboardEmbedSchema.safeParse(raw)
     if (!parsed.success)
       throw new Error(describeSchemaIssues(parsed.error.issues, EMBED_BLOCK_KINDS).join('\n'))
-    validateDashboardBlocks(parsed.data.blocks, parsed.data.source, MAX_DASHBOARD_EMBED_BLOCKS)
+    validateDashboardBlocks(
+      parsed.data.blocks,
+      parsed.data.source,
+      MAX_DASHBOARD_EMBED_BLOCKS,
+      parsed.data.highlights
+    )
     return { spec: parsed.data }
   } catch (error) {
     return { error: getErrorMessage(error, 'Invalid dashboard embed') }