From 12e44f81e849d76893ccf24249f78f8573d1a73e Mon Sep 17 00:00:00 2001
From: Alex Fedotyev <61838744+alex-fedotyev@users.noreply.github.com>
Date: Thu, 18 Jun 2026 01:00:15 +0000
Subject: [PATCH 1/5] feat(dashboards): add background trend sparkline to
 number tiles

Number tiles can render a faint line or area sparkline behind the value,
derived from a time-bucketed version of the same query, so the trend over
the selected range is visible at a glance. Useful for SLO / error-budget
tiles where the burn over time matters as much as the current number.

- common-utils: BackgroundChartSchema (line / area + optional palette color
  override) on SharedChartSettingsSchema, mirroring color / colorRules.
- app: NumberTileBackgroundChart draws the sparkline behind DBNumberChart,
  reusing convertToTimeChartConfig + formatResponseForTimeChart for the
  bucketed series. Builder number tiles only; raw SQL has no time dimension
  to bucket.
- Display Settings: a Background chart control (type + optional color),
  gated on builder number tiles.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .changeset/number-tile-background-chart.md    |  15 ++
 .../src/components/BackgroundChartInput.tsx   |  59 +++++
 .../components/ChartDisplaySettingsDrawer.tsx |  22 ++
 .../DBEditTimeChartForm/EditTimeChartForm.tsx |   8 +-
 packages/app/src/components/DBNumberChart.tsx |  19 +-
 .../components/NumberTileBackgroundChart.tsx  | 201 ++++++++++++++++++
 .../__tests__/DBNumberChart.test.tsx          |  44 ++++
 .../NumberTileBackgroundChart.test.tsx        |  46 ++++
 .../common-utils/src/__tests__/types.test.ts  |  41 +++-
 packages/common-utils/src/types.ts            |  32 ++-
 10 files changed, 478 insertions(+), 9 deletions(-)
 create mode 100644 .changeset/number-tile-background-chart.md
 create mode 100644 packages/app/src/components/BackgroundChartInput.tsx
 create mode 100644 packages/app/src/components/NumberTileBackgroundChart.tsx
 create mode 100644 packages/app/src/components/__tests__/NumberTileBackgroundChart.test.tsx

diff --git a/.changeset/number-tile-background-chart.md b/.changeset/number-tile-background-chart.md
new file mode 100644
index 0000000000..07eb9f2929
--- /dev/null
+++ b/.changeset/number-tile-background-chart.md
@@ -0,0 +1,15 @@
+---
+'@hyperdx/app': minor
+'@hyperdx/common-utils': minor
+---
+
+feat(dashboards): add a background trend sparkline to number tiles
+
+Number tiles can now render a faint line or area sparkline behind the value,
+derived from a time-bucketed version of the same query, so the value's trend
+over the selected range is visible at a glance. This is handy for SLO /
+error-budget tiles where the burn over time matters as much as the current
+number. The sparkline inherits the tile's color by default and can be
+overridden to any palette token. Configure it under Display Settings >
+Background chart on a number tile. Available on builder number tiles (raw SQL
+number tiles return a single value with no time dimension to bucket).
diff --git a/packages/app/src/components/BackgroundChartInput.tsx b/packages/app/src/components/BackgroundChartInput.tsx
new file mode 100644
index 0000000000..d4f04acf69
--- /dev/null
+++ b/packages/app/src/components/BackgroundChartInput.tsx
@@ -0,0 +1,59 @@
+import { BackgroundChart } from '@hyperdx/common-utils/dist/types';
+import { Box, Select, Text } from '@mantine/core';
+
+import { ColorSwatchInput } from './ColorSwatchInput';
+
+const TYPE_OPTIONS = [
+  { value: 'none', label: 'None' },
+  { value: 'line', label: 'Line' },
+  { value: 'area', label: 'Area' },
+];
+
+/**
+ * Editor for a number tile's optional background sparkline. The type select
+ * drives the `backgroundChart` config object: "None" clears it, "Line" /
+ * "Area" set the shape. The color swatch is an optional palette-token
+ * override; when left unset the sparkline inherits the tile's static color.
+ */
+export function BackgroundChartInput({
+  value,
+  onChange,
+}: {
+  value?: BackgroundChart;
+  onChange: (value: BackgroundChart | undefined) => void;
+}) {
+  return (
+    <Box>
+      <Text size="xs" c="dimmed" mb={4}>
+        Background chart
+      </Text>
+      <Select
+        size="xs"
+        data={TYPE_OPTIONS}
+        value={value?.type ?? 'none'}
+        allowDeselect={false}
+        comboboxProps={{ withinPortal: false }}
+        aria-label="Number tile background chart type"
+        onChange={next => {
+          if (next === 'line' || next === 'area') {
+            onChange({ type: next, color: value?.color });
+          } else {
+            onChange(undefined);
+          }
+        }}
+      />
+      {value && (
+        <Box mt="xs">
+          <Text size="xs" c="dimmed" mb={4}>
+            Background color
+          </Text>
+          <ColorSwatchInput
+            value={value.color}
+            onChange={color => onChange({ type: value.type, color })}
+            ariaLabel="Number tile background chart color"
+          />
+        </Box>
+      )}
+    </Box>
+  );
+}
diff --git a/packages/app/src/components/ChartDisplaySettingsDrawer.tsx b/packages/app/src/components/ChartDisplaySettingsDrawer.tsx
index a1aa110401..8abf94d7d7 100644
--- a/packages/app/src/components/ChartDisplaySettingsDrawer.tsx
+++ b/packages/app/src/components/ChartDisplaySettingsDrawer.tsx
@@ -22,6 +22,7 @@ import { shouldFillNullsWithZero } from '@/ChartUtils';
 import { DEFAULT_SERIES_LIMIT } from '@/defaults';
 import { FormatTime } from '@/useFormatTime';
 
+import { BackgroundChartInput } from './BackgroundChartInput';
 import {
   attachLocalIds,
   ColorRulesEditor,
@@ -41,6 +42,7 @@ export type ChartConfigDisplaySettings = Pick<
   | 'fitYAxisToData'
   | 'color'
   | 'colorRules'
+  | 'backgroundChart'
 > & {
   groupByColumnsOnLeft?: boolean;
   // Per-tile cap on the number of series fetched for a group-by time chart.
@@ -95,6 +97,7 @@ function applyDefaultSettings(
     colorRules: settings.colorRules
       ? attachLocalIds(settings.colorRules)
       : undefined,
+    backgroundChart: settings.backgroundChart,
   };
 }
 
@@ -168,6 +171,12 @@ export default function ChartDisplaySettingsDrawer({
   // `select[i].color`.
   const showTileColor = displayType === DisplayType.Number;
 
+  // The background sparkline is derived from a time-bucketed version of the
+  // tile's query, so it only applies to builder number tiles. Raw SQL number
+  // tiles return a single value with no time dimension to bucket.
+  const showBackgroundChart =
+    displayType === DisplayType.Number && configType !== 'sql';
+
   return (
     <Drawer
       title="Display Settings"
@@ -286,6 +295,19 @@ export default function ChartDisplaySettingsDrawer({
           </>
         )}
 
+        {showBackgroundChart && (
+          <>
+            <Controller
+              control={control}
+              name="backgroundChart"
+              render={({ field: { onChange, value } }) => (
+                <BackgroundChartInput value={value} onChange={onChange} />
+              )}
+            />
+            <Divider />
+          </>
+        )}
+
         <NumberFormatForm
           control={control}
           setValue={setValue}
diff --git a/packages/app/src/components/DBEditTimeChartForm/EditTimeChartForm.tsx b/packages/app/src/components/DBEditTimeChartForm/EditTimeChartForm.tsx
index b40e0da570..1283f002fb 100644
--- a/packages/app/src/components/DBEditTimeChartForm/EditTimeChartForm.tsx
+++ b/packages/app/src/components/DBEditTimeChartForm/EditTimeChartForm.tsx
@@ -246,6 +246,7 @@ export default function EditTimeChartForm({
     seriesLimit,
     color,
     colorRules,
+    backgroundChart,
   ] = useWatch({
     control,
     name: [
@@ -258,6 +259,7 @@ export default function EditTimeChartForm({
       'seriesLimit',
       'color',
       'colorRules',
+      'backgroundChart',
     ],
   });
 
@@ -281,6 +283,7 @@ export default function EditTimeChartForm({
       seriesLimit,
       color,
       colorRules,
+      backgroundChart,
     }),
     [
       alignDateRangeToGranularity,
@@ -292,6 +295,7 @@ export default function EditTimeChartForm({
       seriesLimit,
       color,
       colorRules,
+      backgroundChart,
     ],
   );
 
@@ -575,6 +579,7 @@ export default function EditTimeChartForm({
       seriesLimit,
       color,
       colorRules,
+      backgroundChart,
     }: ChartConfigDisplaySettings) => {
       setValue('numberFormat', numberFormat);
       setValue('alignDateRangeToGranularity', alignDateRangeToGranularity);
@@ -583,11 +588,12 @@ export default function EditTimeChartForm({
       setValue('fitYAxisToData', fitYAxisToData);
       setValue('groupByColumnsOnLeft', groupByColumnsOnLeft);
       // Persist `null` (not undefined) when cleared so the disabled state
-      // survives JSON round-tripping through the URL query state — otherwise
+      // survives JSON round-tripping through the URL query state; otherwise
       // the dropped key lets RHF's `values` sync restore the stale value.
       setValue('seriesLimit', seriesLimit ?? null);
       setValue('color', color);
       setValue('colorRules', colorRules);
+      setValue('backgroundChart', backgroundChart);
       onSubmit();
     },
     [setValue, onSubmit],
diff --git a/packages/app/src/components/DBNumberChart.tsx b/packages/app/src/components/DBNumberChart.tsx
index 912580c275..685b9c5eac 100644
--- a/packages/app/src/components/DBNumberChart.tsx
+++ b/packages/app/src/components/DBNumberChart.tsx
@@ -32,6 +32,7 @@ import ChartErrorState, {
   ChartErrorStateVariant,
 } from './charts/ChartErrorState';
 import MVOptimizationIndicator from './MaterializedViews/MVOptimizationIndicator';
+import NumberTileBackgroundChart from './NumberTileBackgroundChart';
 
 const NUMBER_TILE_MIN_FONT_SIZE = 10;
 const NUMBER_TILE_MAX_FONT_SIZE = 72;
@@ -180,7 +181,7 @@ function AutoSizeNumber({
 }
 
 // Wraps AutoSizeNumber in an error boundary so a runtime failure in the
-// measurement / ResizeObserver pipeline never blanks out the tile —
+// measurement / ResizeObserver pipeline never blanks out the tile;
 // instead the dashboard falls back to the original fixed-size rendering.
 function SafeAutoSizeNumber({
   children,
@@ -361,9 +362,19 @@ export default function DBNumberChart({
           No data found within time range.
         </div>
       ) : (
-        <SafeAutoSizeNumber color={tileColor}>
-          {formattedValue ?? 'N/A'}
-        </SafeAutoSizeNumber>
+        <div style={{ position: 'relative', width: '100%', height: '100%' }}>
+          {config.backgroundChart && (
+            <NumberTileBackgroundChart
+              config={config}
+              backgroundChart={config.backgroundChart}
+            />
+          )}
+          <div style={{ position: 'relative', zIndex: 1, height: '100%' }}>
+            <SafeAutoSizeNumber color={tileColor}>
+              {formattedValue ?? 'N/A'}
+            </SafeAutoSizeNumber>
+          </div>
+        </div>
       )}
     </ChartContainer>
   );
diff --git a/packages/app/src/components/NumberTileBackgroundChart.tsx b/packages/app/src/components/NumberTileBackgroundChart.tsx
new file mode 100644
index 0000000000..e27795740a
--- /dev/null
+++ b/packages/app/src/components/NumberTileBackgroundChart.tsx
@@ -0,0 +1,201 @@
+import { useMemo } from 'react';
+import { ErrorBoundary } from 'react-error-boundary';
+import {
+  Area,
+  AreaChart,
+  Line,
+  LineChart,
+  ResponsiveContainer,
+} from 'recharts';
+import { isBuilderChartConfig } from '@hyperdx/common-utils/dist/guards';
+import {
+  BackgroundChart,
+  ChartConfigWithDateRange,
+  ChartPaletteToken,
+  DisplayType,
+  resolveChartPaletteToken,
+} from '@hyperdx/common-utils/dist/types';
+
+import {
+  convertToTimeChartConfig,
+  formatResponseForTimeChart,
+  shouldFillNullsWithZero,
+  useTimeChartSettings,
+} from '@/ChartUtils';
+import { useQueriedChartConfig } from '@/hooks/useChartConfig';
+import { useSource } from '@/source';
+import { getColorFromCSSToken } from '@/utils';
+
+// Trend hue used when neither the background override nor the tile's static
+// `color` is set, so a sparkline is always visible once enabled.
+const DEFAULT_BACKGROUND_TOKEN: ChartPaletteToken = 'chart-blue';
+
+// The sparkline sits behind the value, so it is intentionally low-contrast:
+// a translucent stroke with a fainter area fill.
+const STROKE_OPACITY = 0.5;
+const STROKE_WIDTH = 2;
+const AREA_FILL_OPACITY = 0.15;
+
+// `y` is the plotted value; `x` (bucket timestamp, seconds) is retained for
+// ordering and future axis use. With no `<XAxis>`, recharts spaces points by
+// array order, which is already sorted by bucket.
+const VALUE_KEY = 'y';
+
+type SparklinePoint = { x: number; y: number };
+
+/**
+ * Flatten the time-chart formatter's `graphResults` into sparkline points.
+ * Number tiles are single-series, so a single value series is read by key.
+ * Non-finite values and missing keys are skipped. Exported for unit testing.
+ */
+export function sparklinePointsFromGraphResults(
+  graphResults: Array<Record<string, number | undefined>>,
+  timestampKey: string | undefined,
+  valueKey: string | undefined,
+): SparklinePoint[] {
+  if (!timestampKey || !valueKey) return [];
+  const points: SparklinePoint[] = [];
+  for (const row of graphResults) {
+    const x = row[timestampKey];
+    const y = row[valueKey];
+    if (typeof x === 'number' && typeof y === 'number' && Number.isFinite(y)) {
+      points.push({ x, y });
+    }
+  }
+  return points;
+}
+
+function NumberTileBackgroundChartInner({
+  config,
+  backgroundChart,
+}: {
+  config: ChartConfigWithDateRange;
+  backgroundChart: BackgroundChart;
+}) {
+  // Number tiles strip granularity / group-by (`convertToNumberChartConfig`),
+  // collapsing the query to a single value. Request a line series at the
+  // tile's granularity (auto when unset) to recover the temporal trend.
+  const timeConfig = useMemo<ChartConfigWithDateRange>(
+    () => ({
+      ...config,
+      displayType: DisplayType.Line,
+      granularity: config.granularity ?? 'auto',
+    }),
+    [config],
+  );
+
+  const { dateRange, granularity, fillNulls } =
+    useTimeChartSettings(timeConfig);
+  const queriedConfig = useMemo(
+    () => convertToTimeChartConfig(timeConfig),
+    [timeConfig],
+  );
+
+  const { data } = useQueriedChartConfig(queriedConfig, {
+    placeholderData: prev => prev,
+    queryKey: ['number-tile-background', queriedConfig],
+  });
+
+  const { data: source } = useSource({ id: config.source });
+
+  const points = useMemo(() => {
+    if (data == null) return [];
+    try {
+      const { graphResults, timestampColumn, lineData } =
+        formatResponseForTimeChart({
+          currentPeriodResponse: data,
+          dateRange,
+          granularity,
+          generateEmptyBuckets: shouldFillNullsWithZero(fillNulls),
+          source,
+        });
+      return sparklinePointsFromGraphResults(
+        graphResults,
+        timestampColumn?.name,
+        lineData[0]?.dataKey,
+      );
+    } catch {
+      // No timestamp / value column (e.g. a query that cannot be bucketed):
+      // render nothing rather than surfacing an error behind the value.
+      return [];
+    }
+  }, [data, dateRange, granularity, fillNulls, source]);
+
+  // A single point has no trend to draw; wait for at least two buckets.
+  if (points.length < 2) return null;
+
+  const color = getColorFromCSSToken(
+    backgroundChart.color ??
+      resolveChartPaletteToken(config.color) ??
+      DEFAULT_BACKGROUND_TOKEN,
+  );
+
+  const margin = { top: 4, right: 0, bottom: 0, left: 0 };
+
+  return (
+    <div
+      aria-hidden
+      data-testid="number-tile-background-chart"
+      style={{
+        position: 'absolute',
+        inset: 0,
+        pointerEvents: 'none',
+        zIndex: 0,
+      }}
+    >
+      <ResponsiveContainer width="100%" height="100%">
+        {backgroundChart.type === 'area' ? (
+          <AreaChart data={points} margin={margin}>
+            <Area
+              type="monotone"
+              dataKey={VALUE_KEY}
+              stroke={color}
+              strokeOpacity={STROKE_OPACITY}
+              strokeWidth={STROKE_WIDTH}
+              fill={color}
+              fillOpacity={AREA_FILL_OPACITY}
+              isAnimationActive={false}
+              dot={false}
+            />
+          </AreaChart>
+        ) : (
+          <LineChart data={points} margin={margin}>
+            <Line
+              type="monotone"
+              dataKey={VALUE_KEY}
+              stroke={color}
+              strokeOpacity={STROKE_OPACITY}
+              strokeWidth={STROKE_WIDTH}
+              isAnimationActive={false}
+              dot={false}
+            />
+          </LineChart>
+        )}
+      </ResponsiveContainer>
+    </div>
+  );
+}
+
+/**
+ * Faint line / area sparkline drawn behind a number tile's value. Returns
+ * null for non-builder configs (raw SQL number tiles have no structured time
+ * dimension to bucket) and wraps the renderer in an error boundary so a
+ * sparkline failure never blanks the tile's value.
+ */
+export default function NumberTileBackgroundChart({
+  config,
+  backgroundChart,
+}: {
+  config: ChartConfigWithDateRange;
+  backgroundChart: BackgroundChart;
+}) {
+  if (!isBuilderChartConfig(config)) return null;
+  return (
+    <ErrorBoundary fallback={<span />}>
+      <NumberTileBackgroundChartInner
+        config={config}
+        backgroundChart={backgroundChart}
+      />
+    </ErrorBoundary>
+  );
+}
diff --git a/packages/app/src/components/__tests__/DBNumberChart.test.tsx b/packages/app/src/components/__tests__/DBNumberChart.test.tsx
index 7d363c50ef..7d5d1db570 100644
--- a/packages/app/src/components/__tests__/DBNumberChart.test.tsx
+++ b/packages/app/src/components/__tests__/DBNumberChart.test.tsx
@@ -10,6 +10,7 @@ import { NumberFormat } from '../../types';
 import DateRangeIndicator from '../charts/DateRangeIndicator';
 import DBNumberChart from '../DBNumberChart';
 import MVOptimizationIndicator from '../MaterializedViews/MVOptimizationIndicator';
+import NumberTileBackgroundChart from '../NumberTileBackgroundChart';
 
 // Mock dependencies
 jest.mock('@/hooks/useChartConfig', () => ({
@@ -53,6 +54,13 @@ jest.mock('../MaterializedViews/MVOptimizationIndicator', () =>
 
 jest.mock('../charts/DateRangeIndicator', () => jest.fn(() => null));
 
+// Stub the sparkline so these tests assert only the wiring (when it mounts
+// and what props it receives); its data path is covered by its own test.
+jest.mock('../NumberTileBackgroundChart', () => ({
+  __esModule: true,
+  default: jest.fn(() => <div data-testid="number-tile-background-chart" />),
+}));
+
 describe('DBNumberChart', () => {
   const mockUseQueriedChartConfig = useQueriedChartConfig as jest.Mock;
   const mockFormatNumber = formatNumber as jest.Mock;
@@ -666,4 +674,40 @@ describe('DBNumberChart', () => {
       }
     });
   });
+
+  describe('background chart', () => {
+    const mockBackgroundChart =
+      NumberTileBackgroundChart as unknown as jest.Mock;
+
+    it('renders the background sparkline when backgroundChart is configured', () => {
+      const config = {
+        ...baseTestConfig,
+        backgroundChart: { type: 'area' as const },
+      };
+
+      renderWithMantine(<DBNumberChart config={config} />);
+
+      expect(
+        screen.getByTestId('number-tile-background-chart'),
+      ).toBeInTheDocument();
+      // The renderer hands the tile config and the backgroundChart settings
+      // straight through to the sparkline.
+      expect(mockBackgroundChart).toHaveBeenCalledWith(
+        expect.objectContaining({
+          config,
+          backgroundChart: { type: 'area' },
+        }),
+        undefined,
+      );
+    });
+
+    it('does not render the background sparkline when backgroundChart is unset', () => {
+      renderWithMantine(<DBNumberChart config={baseTestConfig} />);
+
+      expect(
+        screen.queryByTestId('number-tile-background-chart'),
+      ).not.toBeInTheDocument();
+      expect(mockBackgroundChart).not.toHaveBeenCalled();
+    });
+  });
 });
diff --git a/packages/app/src/components/__tests__/NumberTileBackgroundChart.test.tsx b/packages/app/src/components/__tests__/NumberTileBackgroundChart.test.tsx
new file mode 100644
index 0000000000..69d772af63
--- /dev/null
+++ b/packages/app/src/components/__tests__/NumberTileBackgroundChart.test.tsx
@@ -0,0 +1,46 @@
+import { sparklinePointsFromGraphResults } from '../NumberTileBackgroundChart';
+
+describe('sparklinePointsFromGraphResults', () => {
+  const ts = '__hdx_time_bucket';
+  const value = 'Count';
+
+  it('maps graph results to ordered {x, y} points', () => {
+    const graphResults = [
+      { [ts]: 100, [value]: 5 },
+      { [ts]: 200, [value]: 8 },
+      { [ts]: 300, [value]: 3 },
+    ];
+    expect(sparklinePointsFromGraphResults(graphResults, ts, value)).toEqual([
+      { x: 100, y: 5 },
+      { x: 200, y: 8 },
+      { x: 300, y: 3 },
+    ]);
+  });
+
+  it('returns an empty array when the timestamp key is missing', () => {
+    const graphResults = [{ [ts]: 100, [value]: 5 }];
+    expect(
+      sparklinePointsFromGraphResults(graphResults, undefined, value),
+    ).toEqual([]);
+  });
+
+  it('returns an empty array when the value key is missing', () => {
+    const graphResults = [{ [ts]: 100, [value]: 5 }];
+    expect(
+      sparklinePointsFromGraphResults(graphResults, ts, undefined),
+    ).toEqual([]);
+  });
+
+  it('skips rows with non-finite or absent values', () => {
+    const graphResults = [
+      { [ts]: 100, [value]: 5 },
+      { [ts]: 200, [value]: Number.NaN },
+      { [ts]: 300 },
+      { [ts]: 400, [value]: 9 },
+    ];
+    expect(sparklinePointsFromGraphResults(graphResults, ts, value)).toEqual([
+      { x: 100, y: 5 },
+      { x: 400, y: 9 },
+    ]);
+  });
+});
diff --git a/packages/common-utils/src/__tests__/types.test.ts b/packages/common-utils/src/__tests__/types.test.ts
index e93357798a..12a8755129 100644
--- a/packages/common-utils/src/__tests__/types.test.ts
+++ b/packages/common-utils/src/__tests__/types.test.ts
@@ -1,6 +1,6 @@
 import { z } from 'zod';
 
-import { ColorConditionSchema } from '../types';
+import { BackgroundChartSchema, ColorConditionSchema } from '../types';
 
 describe('ColorConditionSchema', () => {
   // ─── Positive cases ─────────────────────────────────────────────────────────
@@ -282,3 +282,42 @@ describe('colorRules array in SharedChartSettingsSchema', () => {
     expect(rulesSchema.safeParse(rules).success).toBe(false);
   });
 });
+
+describe('BackgroundChartSchema', () => {
+  // ─── Positive cases ─────────────────────────────────────────────────────────
+
+  it.each(['line', 'area'] as const)(
+    'parses type %s without a color override',
+    type => {
+      expect(BackgroundChartSchema.safeParse({ type }).success).toBe(true);
+    },
+  );
+
+  it('parses with a palette-token color override', () => {
+    expect(
+      BackgroundChartSchema.safeParse({ type: 'area', color: 'chart-success' })
+        .success,
+    ).toBe(true);
+  });
+
+  // ─── Negative cases ──────────────────────────────────────────────────────────
+
+  it('rejects an unknown chart type', () => {
+    expect(BackgroundChartSchema.safeParse({ type: 'bar' }).success).toBe(
+      false,
+    );
+  });
+
+  it('rejects a missing type', () => {
+    expect(
+      BackgroundChartSchema.safeParse({ color: 'chart-blue' }).success,
+    ).toBe(false);
+  });
+
+  it('rejects an invalid palette token', () => {
+    expect(
+      BackgroundChartSchema.safeParse({ type: 'line', color: 'not-a-token' })
+        .success,
+    ).toBe(false);
+  });
+});
diff --git a/packages/common-utils/src/types.ts b/packages/common-utils/src/types.ts
index e9675539d2..8513e6e802 100644
--- a/packages/common-utils/src/types.ts
+++ b/packages/common-utils/src/types.ts
@@ -804,7 +804,7 @@ export function isOnClickDashboardById(
  *
  * `chart-info` is a render-time CSS variable (defined in the shared
  * `chart-semantic-tokens` SCSS mixin) but is intentionally *not* in the
- * picker enum — it's consumed only by code paths that always want
+ * picker enum; it's consumed only by code paths that always want
  * brand-primary (e.g. info-level log series, `getChartColorInfo()`).
  *
  * Storing tokens (not hex) lets user choices reflow correctly across
@@ -1002,7 +1002,7 @@ export function walkRawDashboardTileColors(
 /**
  * Strict Zod schema for the curated palette tokens. Intentionally
  * does NOT accept legacy numeric tokens (`chart-1` .. `chart-10`)
- * from #2265 — wrapping the enum in `z.preprocess` would force the
+ * from #2265. Wrapping the enum in `z.preprocess` would force the
  * schema's input type to `unknown`, which breaks downstream `z.infer`
  * consumers (e.g. `validateRequest` in the API handlers infers
  * `req.body` as `unknown` for any field reached through this schema).
@@ -1116,6 +1116,26 @@ export type NumberTileColorCondition = z.infer<
   typeof NumberTileColorConditionSchema
 >;
 
+/**
+ * Optional background trend ("sparkline") drawn behind a number tile's
+ * value. Derived from a time-bucketed version of the same query, so the
+ * value's trend over the selected range is visible at a glance (useful for
+ * SLO / error-budget tiles, where burn is temporal).
+ *
+ * `type` picks the shape (`line` or `area`). `color` is an optional
+ * palette-token override; when unset the sparkline inherits the tile's
+ * static `color`. Number tiles only; the UI gates the control on a builder
+ * config (raw SQL number tiles return a single value with no time
+ * dimension to bucket). Lives in common-utils so both the app and a future
+ * external-API parity PR can import it.
+ */
+export const BackgroundChartSchema = z.object({
+  type: z.enum(['line', 'area']),
+  color: ChartPaletteTokenSchema.optional(),
+});
+
+export type BackgroundChart = z.infer<typeof BackgroundChartSchema>;
+
 // When making changes here, consider if they need to be made to the external API
 // as well: the Zod schema (packages/api/src/utils/zod.ts) and the hand-written
 // OpenAPI JSDoc (packages/api/src/routers/external-api/v2/dashboards.ts), which
@@ -1146,6 +1166,12 @@ const SharedChartSettingsSchema = z.object({
   // table-tile slice can attach per-column rules without a schema change.
   // The UI gates the section on `displayType === DisplayType.Number`.
   colorRules: z.array(ColorConditionSchema).max(10).optional(),
+  // Optional background trend (line / area sparkline) drawn behind a number
+  // tile's value, derived from a time-bucketed version of the same query.
+  // Number tiles only; the UI gates the control on a builder config (raw SQL
+  // number tiles have no time dimension to bucket). Other display types
+  // ignore the field. Kept at shared level mirroring `color` / `colorRules`.
+  backgroundChart: BackgroundChartSchema.optional(),
 });
 
 export const _ChartConfigSchema = SharedChartSettingsSchema.extend({
@@ -1708,7 +1734,7 @@ export const LogSourceSchema = BaseSourceSchema.extend({
   implicitColumnExpression: z.string().optional(),
   /**
    * @deprecated Application-side SQL predicate AND'd into every query against
-   * the source. Not a security boundary — bypassable by direct table SELECT.
+   * the source. Not a security boundary; bypassable by direct table SELECT.
    * For hard tenant isolation, use a ClickHouse ROW POLICY at the DB level:
    * https://clickhouse.com/docs/sql-reference/statements/create/row-policy
    *

From fcb80bd818291c64f21bb61c4e2e0af0c7ca2c76 Mon Sep 17 00:00:00 2001
From: Alex Fedotyev <61838744+alex-fedotyev@users.noreply.github.com>
Date: Thu, 18 Jun 2026 20:36:48 +0000
Subject: [PATCH 2/5] feat(dashboards): add a reference line to the number-tile
 sparkline

Adds an optional horizontal reference line to the background sparkline
(value plus optional label and palette color), so a number tile can mark a
0 error budget, an SLA, or a target. Rendered via a recharts ReferenceLine
with a hidden YAxis and ifOverflow="extendDomain" so it stays visible when
the value sits outside the data range.

- common-utils: backgroundChart.referenceLine { value, label?, color? }.
- app: NumberTileBackgroundChart draws the line on the area / line sparkline;
  BackgroundChartInput gains value / label / color controls.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .changeset/number-tile-background-chart.md    |  8 +-
 .../src/components/BackgroundChartInput.tsx   | 95 ++++++++++++++++---
 .../components/NumberTileBackgroundChart.tsx  | 36 +++++++
 .../common-utils/src/__tests__/types.test.ts  | 56 +++++++++++
 packages/common-utils/src/types.ts            | 12 +++
 5 files changed, 191 insertions(+), 16 deletions(-)

diff --git a/.changeset/number-tile-background-chart.md b/.changeset/number-tile-background-chart.md
index 07eb9f2929..0369ab6d66 100644
--- a/.changeset/number-tile-background-chart.md
+++ b/.changeset/number-tile-background-chart.md
@@ -10,6 +10,8 @@ derived from a time-bucketed version of the same query, so the value's trend
 over the selected range is visible at a glance. This is handy for SLO /
 error-budget tiles where the burn over time matters as much as the current
 number. The sparkline inherits the tile's color by default and can be
-overridden to any palette token. Configure it under Display Settings >
-Background chart on a number tile. Available on builder number tiles (raw SQL
-number tiles return a single value with no time dimension to bucket).
+overridden to any palette token, and you can add a reference line (with an
+optional label and color) to mark a value such as a 0 error budget, an SLA, or
+a target. Configure it under Display Settings > Background chart on a number
+tile. Available on builder number tiles (raw SQL number tiles return a single
+value with no time dimension to bucket).
diff --git a/packages/app/src/components/BackgroundChartInput.tsx b/packages/app/src/components/BackgroundChartInput.tsx
index d4f04acf69..95bf43413d 100644
--- a/packages/app/src/components/BackgroundChartInput.tsx
+++ b/packages/app/src/components/BackgroundChartInput.tsx
@@ -1,5 +1,5 @@
 import { BackgroundChart } from '@hyperdx/common-utils/dist/types';
-import { Box, Select, Text } from '@mantine/core';
+import { Box, NumberInput, Select, Text, TextInput } from '@mantine/core';
 
 import { ColorSwatchInput } from './ColorSwatchInput';
 
@@ -13,7 +13,9 @@ const TYPE_OPTIONS = [
  * Editor for a number tile's optional background sparkline. The type select
  * drives the `backgroundChart` config object: "None" clears it, "Line" /
  * "Area" set the shape. The color swatch is an optional palette-token
- * override; when left unset the sparkline inherits the tile's static color.
+ * override; when unset the sparkline inherits the tile's static color. An
+ * optional reference line marks a value on the sparkline (for example a 0
+ * error-budget line, an SLA, or a target).
  */
 export function BackgroundChartInput({
   value,
@@ -22,6 +24,8 @@ export function BackgroundChartInput({
   value?: BackgroundChart;
   onChange: (value: BackgroundChart | undefined) => void;
 }) {
+  const referenceLine = value?.referenceLine;
+
   return (
     <Box>
       <Text size="xs" c="dimmed" mb={4}>
@@ -36,23 +40,88 @@ export function BackgroundChartInput({
         aria-label="Number tile background chart type"
         onChange={next => {
           if (next === 'line' || next === 'area') {
-            onChange({ type: next, color: value?.color });
+            onChange({ ...value, type: next });
           } else {
             onChange(undefined);
           }
         }}
       />
       {value && (
-        <Box mt="xs">
-          <Text size="xs" c="dimmed" mb={4}>
-            Background color
-          </Text>
-          <ColorSwatchInput
-            value={value.color}
-            onChange={color => onChange({ type: value.type, color })}
-            ariaLabel="Number tile background chart color"
-          />
-        </Box>
+        <>
+          <Box mt="xs">
+            <Text size="xs" c="dimmed" mb={4}>
+              Background color
+            </Text>
+            <ColorSwatchInput
+              value={value.color}
+              onChange={color => onChange({ ...value, color })}
+              ariaLabel="Number tile background chart color"
+            />
+          </Box>
+
+          <Box mt="xs">
+            <Text size="xs" c="dimmed" mb={4}>
+              Reference line
+            </Text>
+            <NumberInput
+              size="xs"
+              placeholder="Value (e.g. 0 for an error budget, or an SLA)"
+              value={referenceLine?.value ?? ''}
+              onChange={v => {
+                if (v === '' || v == null) {
+                  // Clearing the value removes the reference line entirely.
+                  const { referenceLine: _drop, ...rest } = value;
+                  onChange(rest);
+                } else {
+                  onChange({
+                    ...value,
+                    referenceLine: { ...referenceLine, value: Number(v) },
+                  });
+                }
+              }}
+            />
+          </Box>
+
+          {referenceLine && (
+            <>
+              <Box mt="xs">
+                <Text size="xs" c="dimmed" mb={4}>
+                  Reference line label
+                </Text>
+                <TextInput
+                  size="xs"
+                  maxLength={40}
+                  placeholder="Optional (e.g. Budget, SLA)"
+                  value={referenceLine.label ?? ''}
+                  onChange={e =>
+                    onChange({
+                      ...value,
+                      referenceLine: {
+                        ...referenceLine,
+                        label: e.currentTarget.value || undefined,
+                      },
+                    })
+                  }
+                />
+              </Box>
+              <Box mt="xs">
+                <Text size="xs" c="dimmed" mb={4}>
+                  Reference line color
+                </Text>
+                <ColorSwatchInput
+                  value={referenceLine.color}
+                  onChange={color =>
+                    onChange({
+                      ...value,
+                      referenceLine: { ...referenceLine, color },
+                    })
+                  }
+                  ariaLabel="Reference line color"
+                />
+              </Box>
+            </>
+          )}
+        </>
       )}
     </Box>
   );
diff --git a/packages/app/src/components/NumberTileBackgroundChart.tsx b/packages/app/src/components/NumberTileBackgroundChart.tsx
index e27795740a..4e76fd2f6a 100644
--- a/packages/app/src/components/NumberTileBackgroundChart.tsx
+++ b/packages/app/src/components/NumberTileBackgroundChart.tsx
@@ -5,7 +5,9 @@ import {
   AreaChart,
   Line,
   LineChart,
+  ReferenceLine,
   ResponsiveContainer,
+  YAxis,
 } from 'recharts';
 import { isBuilderChartConfig } from '@hyperdx/common-utils/dist/guards';
 import {
@@ -132,6 +134,36 @@ function NumberTileBackgroundChartInner({
 
   const margin = { top: 4, right: 0, bottom: 0, left: 0 };
 
+  // Optional reference line (e.g. a 0 budget line, an SLA, or a target).
+  // A hidden YAxis gives recharts a value scale to position it on, and
+  // `ifOverflow="extendDomain"` keeps the line visible when the value sits
+  // outside the data range. Both are direct chart children (recharts does not
+  // see them through a fragment), reused across the area / line branches.
+  const refLine = backgroundChart.referenceLine;
+  const refColor = refLine
+    ? getColorFromCSSToken(refLine.color ?? 'chart-warning')
+    : undefined;
+  const yAxisEl = refLine ? <YAxis hide domain={['auto', 'auto']} /> : null;
+  const refLineEl = refLine ? (
+    <ReferenceLine
+      y={refLine.value}
+      stroke={refColor}
+      strokeOpacity={STROKE_OPACITY}
+      strokeDasharray="4 3"
+      ifOverflow="extendDomain"
+      label={
+        refLine.label
+          ? {
+              value: refLine.label,
+              position: 'insideTopRight',
+              fontSize: 10,
+              fill: refColor,
+            }
+          : undefined
+      }
+    />
+  ) : null;
+
   return (
     <div
       aria-hidden
@@ -146,6 +178,8 @@ function NumberTileBackgroundChartInner({
       <ResponsiveContainer width="100%" height="100%">
         {backgroundChart.type === 'area' ? (
           <AreaChart data={points} margin={margin}>
+            {yAxisEl}
+            {refLineEl}
             <Area
               type="monotone"
               dataKey={VALUE_KEY}
@@ -160,6 +194,8 @@ function NumberTileBackgroundChartInner({
           </AreaChart>
         ) : (
           <LineChart data={points} margin={margin}>
+            {yAxisEl}
+            {refLineEl}
             <Line
               type="monotone"
               dataKey={VALUE_KEY}
diff --git a/packages/common-utils/src/__tests__/types.test.ts b/packages/common-utils/src/__tests__/types.test.ts
index 12a8755129..00a11eef65 100644
--- a/packages/common-utils/src/__tests__/types.test.ts
+++ b/packages/common-utils/src/__tests__/types.test.ts
@@ -320,4 +320,60 @@ describe('BackgroundChartSchema', () => {
         .success,
     ).toBe(false);
   });
+
+  // ─── Reference line ─────────────────────────────────────────────────────────
+
+  it('parses with a reference line value', () => {
+    expect(
+      BackgroundChartSchema.safeParse({
+        type: 'area',
+        referenceLine: { value: 0 },
+      }).success,
+    ).toBe(true);
+  });
+
+  it('parses a reference line with label and color', () => {
+    expect(
+      BackgroundChartSchema.safeParse({
+        type: 'line',
+        referenceLine: { value: 99.9, label: 'SLA', color: 'chart-warning' },
+      }).success,
+    ).toBe(true);
+  });
+
+  it('rejects a reference line without a value', () => {
+    expect(
+      BackgroundChartSchema.safeParse({
+        type: 'area',
+        referenceLine: { label: 'SLA' },
+      }).success,
+    ).toBe(false);
+  });
+
+  it('rejects a non-finite reference line value', () => {
+    expect(
+      BackgroundChartSchema.safeParse({
+        type: 'area',
+        referenceLine: { value: Number.POSITIVE_INFINITY },
+      }).success,
+    ).toBe(false);
+  });
+
+  it('rejects an invalid reference line color', () => {
+    expect(
+      BackgroundChartSchema.safeParse({
+        type: 'area',
+        referenceLine: { value: 0, color: 'not-a-token' },
+      }).success,
+    ).toBe(false);
+  });
+
+  it('rejects a reference line label longer than 40 chars', () => {
+    expect(
+      BackgroundChartSchema.safeParse({
+        type: 'area',
+        referenceLine: { value: 0, label: 'a'.repeat(41) },
+      }).success,
+    ).toBe(false);
+  });
 });
diff --git a/packages/common-utils/src/types.ts b/packages/common-utils/src/types.ts
index 8513e6e802..c7b25123c7 100644
--- a/packages/common-utils/src/types.ts
+++ b/packages/common-utils/src/types.ts
@@ -1132,6 +1132,18 @@ export type NumberTileColorCondition = z.infer<
 export const BackgroundChartSchema = z.object({
   type: z.enum(['line', 'area']),
   color: ChartPaletteTokenSchema.optional(),
+  // Optional horizontal reference line drawn across the sparkline (for
+  // example a 0 error-budget line, an SLA, or a target). `value` is where the
+  // line sits on the value axis; the renderer extends the axis domain to
+  // include it so the line is always visible. `label` is an optional caption,
+  // `color` an optional palette-token override (defaults to a warning hue).
+  referenceLine: z
+    .object({
+      value: z.number().finite(),
+      label: z.string().max(40).optional(),
+      color: ChartPaletteTokenSchema.optional(),
+    })
+    .optional(),
 });
 
 export type BackgroundChart = z.infer<typeof BackgroundChartSchema>;

From 79f69f4edfdae9b0225dd4821307ee08762fa3a2 Mon Sep 17 00:00:00 2001
From: Alex Fedotyev <61838744+alex-fedotyev@users.noreply.github.com>
Date: Thu, 18 Jun 2026 23:14:02 +0000
Subject: [PATCH 3/5] fix(dashboards): keep the number-tile sparkline query
 stable across visual edits

Addresses code review on NumberTileBackgroundChart:
- Strip display-only fields (backgroundChart, color, colorRules, numberFormat)
  before building the sparkline's time-series query, so they no longer enter
  the TanStack query key and refetch identical data on a purely visual edit
  (sparkline type, reference line, tile color, number format).
- Guard the bucket timestamp with Number.isFinite as well, mirroring the value
  check, so a degenerate timestamp cannot reach recharts.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../components/NumberTileBackgroundChart.tsx  | 30 ++++++++++++++-----
 .../NumberTileBackgroundChart.test.tsx        | 11 +++++++
 2 files changed, 34 insertions(+), 7 deletions(-)

diff --git a/packages/app/src/components/NumberTileBackgroundChart.tsx b/packages/app/src/components/NumberTileBackgroundChart.tsx
index 4e76fd2f6a..f8e50e0d00 100644
--- a/packages/app/src/components/NumberTileBackgroundChart.tsx
+++ b/packages/app/src/components/NumberTileBackgroundChart.tsx
@@ -60,7 +60,12 @@ export function sparklinePointsFromGraphResults(
   for (const row of graphResults) {
     const x = row[timestampKey];
     const y = row[valueKey];
-    if (typeof x === 'number' && typeof y === 'number' && Number.isFinite(y)) {
+    if (
+      typeof x === 'number' &&
+      Number.isFinite(x) &&
+      typeof y === 'number' &&
+      Number.isFinite(y)
+    ) {
       points.push({ x, y });
     }
   }
@@ -77,14 +82,25 @@ function NumberTileBackgroundChartInner({
   // Number tiles strip granularity / group-by (`convertToNumberChartConfig`),
   // collapsing the query to a single value. Request a line series at the
   // tile's granularity (auto when unset) to recover the temporal trend.
-  const timeConfig = useMemo<ChartConfigWithDateRange>(
-    () => ({
-      ...config,
+  //
+  // Drop number-tile display-only fields first: they flow into the query key
+  // (via `convertToTimeChartConfig`), so leaving them in would refetch
+  // identical time-series data on every purely visual edit (sparkline type,
+  // reference line, tile color, number format).
+  const timeConfig = useMemo<ChartConfigWithDateRange>(() => {
+    const {
+      backgroundChart: _backgroundChart,
+      color: _color,
+      colorRules: _colorRules,
+      numberFormat: _numberFormat,
+      ...rest
+    } = config;
+    return {
+      ...rest,
       displayType: DisplayType.Line,
       granularity: config.granularity ?? 'auto',
-    }),
-    [config],
-  );
+    };
+  }, [config]);
 
   const { dateRange, granularity, fillNulls } =
     useTimeChartSettings(timeConfig);
diff --git a/packages/app/src/components/__tests__/NumberTileBackgroundChart.test.tsx b/packages/app/src/components/__tests__/NumberTileBackgroundChart.test.tsx
index 69d772af63..8fca1d3152 100644
--- a/packages/app/src/components/__tests__/NumberTileBackgroundChart.test.tsx
+++ b/packages/app/src/components/__tests__/NumberTileBackgroundChart.test.tsx
@@ -43,4 +43,15 @@ describe('sparklinePointsFromGraphResults', () => {
       { x: 400, y: 9 },
     ]);
   });
+
+  it('skips rows with a non-finite timestamp', () => {
+    const graphResults = [
+      { [ts]: Number.NaN, [value]: 5 },
+      { [ts]: Number.POSITIVE_INFINITY, [value]: 6 },
+      { [ts]: 300, [value]: 9 },
+    ];
+    expect(sparklinePointsFromGraphResults(graphResults, ts, value)).toEqual([
+      { x: 300, y: 9 },
+    ]);
+  });
 });

From 84fb7744af315a5513b56cbe71b0b10adf879331 Mon Sep 17 00:00:00 2001
From: Alex Fedotyev <61838744+alex-fedotyev@users.noreply.github.com>
Date: Fri, 19 Jun 2026 00:21:12 +0000
Subject: [PATCH 4/5] refactor(dashboards): drop the number-tile sparkline
 reference line

Per review, a reference line on the axis-less background sparkline reads as
confusing: there is no visible scale to anchor it, and it blurs against the
value and the conditional color rules. Reference lines belong on full line /
stacked-bar tiles, where they have real axes, and will ship in that slice
instead. This keeps the number-tile feature to just the background sparkline.

Removes backgroundChart.referenceLine from the schema, the recharts
ReferenceLine + hidden YAxis from the renderer, and the reference-line
controls from the editor.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .changeset/number-tile-background-chart.md    |  8 +-
 .../src/components/BackgroundChartInput.tsx   | 93 +++----------------
 .../components/NumberTileBackgroundChart.tsx  | 38 +-------
 .../common-utils/src/__tests__/types.test.ts  | 56 -----------
 packages/common-utils/src/types.ts            | 12 ---
 5 files changed, 16 insertions(+), 191 deletions(-)

diff --git a/.changeset/number-tile-background-chart.md b/.changeset/number-tile-background-chart.md
index 0369ab6d66..07eb9f2929 100644
--- a/.changeset/number-tile-background-chart.md
+++ b/.changeset/number-tile-background-chart.md
@@ -10,8 +10,6 @@ derived from a time-bucketed version of the same query, so the value's trend
 over the selected range is visible at a glance. This is handy for SLO /
 error-budget tiles where the burn over time matters as much as the current
 number. The sparkline inherits the tile's color by default and can be
-overridden to any palette token, and you can add a reference line (with an
-optional label and color) to mark a value such as a 0 error budget, an SLA, or
-a target. Configure it under Display Settings > Background chart on a number
-tile. Available on builder number tiles (raw SQL number tiles return a single
-value with no time dimension to bucket).
+overridden to any palette token. Configure it under Display Settings >
+Background chart on a number tile. Available on builder number tiles (raw SQL
+number tiles return a single value with no time dimension to bucket).
diff --git a/packages/app/src/components/BackgroundChartInput.tsx b/packages/app/src/components/BackgroundChartInput.tsx
index 95bf43413d..a2268f06d7 100644
--- a/packages/app/src/components/BackgroundChartInput.tsx
+++ b/packages/app/src/components/BackgroundChartInput.tsx
@@ -1,5 +1,5 @@
 import { BackgroundChart } from '@hyperdx/common-utils/dist/types';
-import { Box, NumberInput, Select, Text, TextInput } from '@mantine/core';
+import { Box, Select, Text } from '@mantine/core';
 
 import { ColorSwatchInput } from './ColorSwatchInput';
 
@@ -13,9 +13,7 @@ const TYPE_OPTIONS = [
  * Editor for a number tile's optional background sparkline. The type select
  * drives the `backgroundChart` config object: "None" clears it, "Line" /
  * "Area" set the shape. The color swatch is an optional palette-token
- * override; when unset the sparkline inherits the tile's static color. An
- * optional reference line marks a value on the sparkline (for example a 0
- * error-budget line, an SLA, or a target).
+ * override; when unset the sparkline inherits the tile's static color.
  */
 export function BackgroundChartInput({
   value,
@@ -24,8 +22,6 @@ export function BackgroundChartInput({
   value?: BackgroundChart;
   onChange: (value: BackgroundChart | undefined) => void;
 }) {
-  const referenceLine = value?.referenceLine;
-
   return (
     <Box>
       <Text size="xs" c="dimmed" mb={4}>
@@ -47,81 +43,16 @@ export function BackgroundChartInput({
         }}
       />
       {value && (
-        <>
-          <Box mt="xs">
-            <Text size="xs" c="dimmed" mb={4}>
-              Background color
-            </Text>
-            <ColorSwatchInput
-              value={value.color}
-              onChange={color => onChange({ ...value, color })}
-              ariaLabel="Number tile background chart color"
-            />
-          </Box>
-
-          <Box mt="xs">
-            <Text size="xs" c="dimmed" mb={4}>
-              Reference line
-            </Text>
-            <NumberInput
-              size="xs"
-              placeholder="Value (e.g. 0 for an error budget, or an SLA)"
-              value={referenceLine?.value ?? ''}
-              onChange={v => {
-                if (v === '' || v == null) {
-                  // Clearing the value removes the reference line entirely.
-                  const { referenceLine: _drop, ...rest } = value;
-                  onChange(rest);
-                } else {
-                  onChange({
-                    ...value,
-                    referenceLine: { ...referenceLine, value: Number(v) },
-                  });
-                }
-              }}
-            />
-          </Box>
-
-          {referenceLine && (
-            <>
-              <Box mt="xs">
-                <Text size="xs" c="dimmed" mb={4}>
-                  Reference line label
-                </Text>
-                <TextInput
-                  size="xs"
-                  maxLength={40}
-                  placeholder="Optional (e.g. Budget, SLA)"
-                  value={referenceLine.label ?? ''}
-                  onChange={e =>
-                    onChange({
-                      ...value,
-                      referenceLine: {
-                        ...referenceLine,
-                        label: e.currentTarget.value || undefined,
-                      },
-                    })
-                  }
-                />
-              </Box>
-              <Box mt="xs">
-                <Text size="xs" c="dimmed" mb={4}>
-                  Reference line color
-                </Text>
-                <ColorSwatchInput
-                  value={referenceLine.color}
-                  onChange={color =>
-                    onChange({
-                      ...value,
-                      referenceLine: { ...referenceLine, color },
-                    })
-                  }
-                  ariaLabel="Reference line color"
-                />
-              </Box>
-            </>
-          )}
-        </>
+        <Box mt="xs">
+          <Text size="xs" c="dimmed" mb={4}>
+            Background color
+          </Text>
+          <ColorSwatchInput
+            value={value.color}
+            onChange={color => onChange({ ...value, color })}
+            ariaLabel="Number tile background chart color"
+          />
+        </Box>
       )}
     </Box>
   );
diff --git a/packages/app/src/components/NumberTileBackgroundChart.tsx b/packages/app/src/components/NumberTileBackgroundChart.tsx
index f8e50e0d00..22d57fdc46 100644
--- a/packages/app/src/components/NumberTileBackgroundChart.tsx
+++ b/packages/app/src/components/NumberTileBackgroundChart.tsx
@@ -5,9 +5,7 @@ import {
   AreaChart,
   Line,
   LineChart,
-  ReferenceLine,
   ResponsiveContainer,
-  YAxis,
 } from 'recharts';
 import { isBuilderChartConfig } from '@hyperdx/common-utils/dist/guards';
 import {
@@ -86,7 +84,7 @@ function NumberTileBackgroundChartInner({
   // Drop number-tile display-only fields first: they flow into the query key
   // (via `convertToTimeChartConfig`), so leaving them in would refetch
   // identical time-series data on every purely visual edit (sparkline type,
-  // reference line, tile color, number format).
+  // tile color, number format).
   const timeConfig = useMemo<ChartConfigWithDateRange>(() => {
     const {
       backgroundChart: _backgroundChart,
@@ -150,36 +148,6 @@ function NumberTileBackgroundChartInner({
 
   const margin = { top: 4, right: 0, bottom: 0, left: 0 };
 
-  // Optional reference line (e.g. a 0 budget line, an SLA, or a target).
-  // A hidden YAxis gives recharts a value scale to position it on, and
-  // `ifOverflow="extendDomain"` keeps the line visible when the value sits
-  // outside the data range. Both are direct chart children (recharts does not
-  // see them through a fragment), reused across the area / line branches.
-  const refLine = backgroundChart.referenceLine;
-  const refColor = refLine
-    ? getColorFromCSSToken(refLine.color ?? 'chart-warning')
-    : undefined;
-  const yAxisEl = refLine ? <YAxis hide domain={['auto', 'auto']} /> : null;
-  const refLineEl = refLine ? (
-    <ReferenceLine
-      y={refLine.value}
-      stroke={refColor}
-      strokeOpacity={STROKE_OPACITY}
-      strokeDasharray="4 3"
-      ifOverflow="extendDomain"
-      label={
-        refLine.label
-          ? {
-              value: refLine.label,
-              position: 'insideTopRight',
-              fontSize: 10,
-              fill: refColor,
-            }
-          : undefined
-      }
-    />
-  ) : null;
-
   return (
     <div
       aria-hidden
@@ -194,8 +162,6 @@ function NumberTileBackgroundChartInner({
       <ResponsiveContainer width="100%" height="100%">
         {backgroundChart.type === 'area' ? (
           <AreaChart data={points} margin={margin}>
-            {yAxisEl}
-            {refLineEl}
             <Area
               type="monotone"
               dataKey={VALUE_KEY}
@@ -210,8 +176,6 @@ function NumberTileBackgroundChartInner({
           </AreaChart>
         ) : (
           <LineChart data={points} margin={margin}>
-            {yAxisEl}
-            {refLineEl}
             <Line
               type="monotone"
               dataKey={VALUE_KEY}
diff --git a/packages/common-utils/src/__tests__/types.test.ts b/packages/common-utils/src/__tests__/types.test.ts
index 00a11eef65..12a8755129 100644
--- a/packages/common-utils/src/__tests__/types.test.ts
+++ b/packages/common-utils/src/__tests__/types.test.ts
@@ -320,60 +320,4 @@ describe('BackgroundChartSchema', () => {
         .success,
     ).toBe(false);
   });
-
-  // ─── Reference line ─────────────────────────────────────────────────────────
-
-  it('parses with a reference line value', () => {
-    expect(
-      BackgroundChartSchema.safeParse({
-        type: 'area',
-        referenceLine: { value: 0 },
-      }).success,
-    ).toBe(true);
-  });
-
-  it('parses a reference line with label and color', () => {
-    expect(
-      BackgroundChartSchema.safeParse({
-        type: 'line',
-        referenceLine: { value: 99.9, label: 'SLA', color: 'chart-warning' },
-      }).success,
-    ).toBe(true);
-  });
-
-  it('rejects a reference line without a value', () => {
-    expect(
-      BackgroundChartSchema.safeParse({
-        type: 'area',
-        referenceLine: { label: 'SLA' },
-      }).success,
-    ).toBe(false);
-  });
-
-  it('rejects a non-finite reference line value', () => {
-    expect(
-      BackgroundChartSchema.safeParse({
-        type: 'area',
-        referenceLine: { value: Number.POSITIVE_INFINITY },
-      }).success,
-    ).toBe(false);
-  });
-
-  it('rejects an invalid reference line color', () => {
-    expect(
-      BackgroundChartSchema.safeParse({
-        type: 'area',
-        referenceLine: { value: 0, color: 'not-a-token' },
-      }).success,
-    ).toBe(false);
-  });
-
-  it('rejects a reference line label longer than 40 chars', () => {
-    expect(
-      BackgroundChartSchema.safeParse({
-        type: 'area',
-        referenceLine: { value: 0, label: 'a'.repeat(41) },
-      }).success,
-    ).toBe(false);
-  });
 });
diff --git a/packages/common-utils/src/types.ts b/packages/common-utils/src/types.ts
index c7b25123c7..8513e6e802 100644
--- a/packages/common-utils/src/types.ts
+++ b/packages/common-utils/src/types.ts
@@ -1132,18 +1132,6 @@ export type NumberTileColorCondition = z.infer<
 export const BackgroundChartSchema = z.object({
   type: z.enum(['line', 'area']),
   color: ChartPaletteTokenSchema.optional(),
-  // Optional horizontal reference line drawn across the sparkline (for
-  // example a 0 error-budget line, an SLA, or a target). `value` is where the
-  // line sits on the value axis; the renderer extends the axis domain to
-  // include it so the line is always visible. `label` is an optional caption,
-  // `color` an optional palette-token override (defaults to a warning hue).
-  referenceLine: z
-    .object({
-      value: z.number().finite(),
-      label: z.string().max(40).optional(),
-      color: ChartPaletteTokenSchema.optional(),
-    })
-    .optional(),
 });
 
 export type BackgroundChart = z.infer<typeof BackgroundChartSchema>;

From 4fa65c99129cee2fc8e7e9b492b715e367222aa8 Mon Sep 17 00:00:00 2001
From: Alex Fedotyev <61838744+alex-fedotyev@users.noreply.github.com>
Date: Fri, 19 Jun 2026 04:48:44 +0000
Subject: [PATCH 5/5] feat(dashboards): show the number-tile background chart
 control disabled on SQL tiles

On a raw SQL number tile the Background chart control was hidden entirely.
Show it disabled with a hint ("Available on query-builder number tiles")
instead, so the option stays discoverable and the slot is already in place
for when SQL background queries land. Builder number tiles are unchanged.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../src/components/BackgroundChartInput.tsx   | 35 +++++++++++++------
 .../components/ChartDisplaySettingsDrawer.tsx | 16 ++++++---
 2 files changed, 35 insertions(+), 16 deletions(-)

diff --git a/packages/app/src/components/BackgroundChartInput.tsx b/packages/app/src/components/BackgroundChartInput.tsx
index a2268f06d7..54d3e5011b 100644
--- a/packages/app/src/components/BackgroundChartInput.tsx
+++ b/packages/app/src/components/BackgroundChartInput.tsx
@@ -14,13 +14,19 @@ const TYPE_OPTIONS = [
  * drives the `backgroundChart` config object: "None" clears it, "Line" /
  * "Area" set the shape. The color swatch is an optional palette-token
  * override; when unset the sparkline inherits the tile's static color.
+ *
+ * `disabled` is set for raw SQL number tiles, which have no time dimension to
+ * bucket: the control stays visible but inert with a hint, so the option is
+ * discoverable rather than missing.
  */
 export function BackgroundChartInput({
   value,
   onChange,
+  disabled = false,
 }: {
   value?: BackgroundChart;
   onChange: (value: BackgroundChart | undefined) => void;
+  disabled?: boolean;
 }) {
   return (
     <Box>
@@ -31,6 +37,7 @@ export function BackgroundChartInput({
         size="xs"
         data={TYPE_OPTIONS}
         value={value?.type ?? 'none'}
+        disabled={disabled}
         allowDeselect={false}
         comboboxProps={{ withinPortal: false }}
         aria-label="Number tile background chart type"
@@ -42,17 +49,23 @@ export function BackgroundChartInput({
           }
         }}
       />
-      {value && (
-        <Box mt="xs">
-          <Text size="xs" c="dimmed" mb={4}>
-            Background color
-          </Text>
-          <ColorSwatchInput
-            value={value.color}
-            onChange={color => onChange({ ...value, color })}
-            ariaLabel="Number tile background chart color"
-          />
-        </Box>
+      {disabled ? (
+        <Text size="xs" c="dimmed" mt={4}>
+          Available on query-builder number tiles.
+        </Text>
+      ) : (
+        value && (
+          <Box mt="xs">
+            <Text size="xs" c="dimmed" mb={4}>
+              Background color
+            </Text>
+            <ColorSwatchInput
+              value={value.color}
+              onChange={color => onChange({ ...value, color })}
+              ariaLabel="Number tile background chart color"
+            />
+          </Box>
+        )
       )}
     </Box>
   );
diff --git a/packages/app/src/components/ChartDisplaySettingsDrawer.tsx b/packages/app/src/components/ChartDisplaySettingsDrawer.tsx
index 8abf94d7d7..1e7b2bbc31 100644
--- a/packages/app/src/components/ChartDisplaySettingsDrawer.tsx
+++ b/packages/app/src/components/ChartDisplaySettingsDrawer.tsx
@@ -172,10 +172,12 @@ export default function ChartDisplaySettingsDrawer({
   const showTileColor = displayType === DisplayType.Number;
 
   // The background sparkline is derived from a time-bucketed version of the
-  // tile's query, so it only applies to builder number tiles. Raw SQL number
-  // tiles return a single value with no time dimension to bucket.
-  const showBackgroundChart =
-    displayType === DisplayType.Number && configType !== 'sql';
+  // tile's query, so it only applies to builder number tiles: raw SQL number
+  // tiles return a single value with no time dimension to bucket. On a SQL
+  // number tile the control is shown disabled with a hint rather than hidden,
+  // so the option stays discoverable.
+  const showBackgroundChart = displayType === DisplayType.Number;
+  const isBackgroundChartDisabled = configType === 'sql';
 
   return (
     <Drawer
@@ -301,7 +303,11 @@ export default function ChartDisplaySettingsDrawer({
               control={control}
               name="backgroundChart"
               render={({ field: { onChange, value } }) => (
-                <BackgroundChartInput value={value} onChange={onChange} />
+                <BackgroundChartInput
+                  value={value}
+                  onChange={onChange}
+                  disabled={isBackgroundChartDisabled}
+                />
               )}
             />
             <Divider />