@opendata-ai/openchart-engine 6.28.6 → 7.0.2

package/src/compiler/__tests__/sparkline-defaults.test.ts

@@ -0,0 +1,153 @@
+/**
+ * Tests for sparkline default resolution.
+ *
+ * Focus: the trend signal must be honest about noisy series and short
+ * series. Naive `last - first` would mislabel `[100, 50, 200, 60, 101]`
+ * as up; a regression slope with deadband correctly reads it as neutral.
+ */
+
+import type { MarkDef, ResolvedTheme } from '@opendata-ai/openchart-core';
+import { describe, expect, it } from 'vitest';
+import {
+  buildSparklineAreaGradient,
+  computeTrend,
+  computeTrendFromData,
+  hasExplicitColor,
+  trendColor,
+} from '../sparkline-defaults';
+
+const baseTheme = {
+  colors: {
+    categorical: ['#1b7fa3', '#aaa'],
+    positive: '#16a34a',
+    negative: '#dc2626',
+  },
+} as unknown as ResolvedTheme;
+
+describe('computeTrend', () => {
+  it('classifies clear up-trend as "up"', () => {
+    expect(computeTrend([1, 2, 3, 4, 5])).toBe('up');
+  });
+
+  it('classifies clear down-trend as "down"', () => {
+    expect(computeTrend([5, 4, 3, 2, 1])).toBe('down');
+  });
+
+  it('classifies flat series as "neutral"', () => {
+    expect(computeTrend([10, 10, 10, 10])).toBe('neutral');
+  });
+
+  it('classifies noisy non-monotonic series with no meaningful net trend as "neutral"', () => {
+    // Symmetric oscillation around the mean — the regression slope works
+    // out to (almost) zero. Naive `last - first` heuristics would classify
+    // this incorrectly; the regression sees no net direction.
+    // Palindromic series — mirrors around the midpoint, so the regression
+    // slope is mathematically zero regardless of the noise amplitude.
+    expect(computeTrend([100, 105, 95, 102, 95, 105, 100])).toBe('neutral');
+  });
+
+  it('classifies a real trend with noise as the net direction', () => {
+    // ~10% net rise over 20 steps with realistic chop — should still read up.
+    const series = [
+      100, 102, 99, 103, 101, 104, 103, 106, 104, 107, 105, 108, 107, 109, 108, 110, 109, 111, 110,
+      112,
+    ];
+    expect(computeTrend(series)).toBe('up');
+  });
+
+  it('returns "neutral" for empty series', () => {
+    expect(computeTrend([])).toBe('neutral');
+  });
+
+  it('returns "neutral" for single-point series', () => {
+    expect(computeTrend([42])).toBe('neutral');
+  });
+
+  it('returns "neutral" when all values are non-finite', () => {
+    expect(computeTrend([NaN, NaN, Infinity])).toBe('neutral');
+  });
+
+  it('skips non-finite values and classifies remaining', () => {
+    expect(computeTrend([NaN, 1, 2, 3, 4, NaN])).toBe('up');
+  });
+
+  it('treats very small relative slope as "neutral" (deadband)', () => {
+    // Slope is real but tiny relative to the mean.
+    expect(computeTrend([1000, 1000.5, 1001, 1001.2])).toBe('neutral');
+  });
+});
+
+describe('computeTrendFromData', () => {
+  it('reads y values from data rows', () => {
+    const data = [
+      { date: 'a', value: 1 },
+      { date: 'b', value: 2 },
+      { date: 'c', value: 3 },
+    ];
+    expect(computeTrendFromData(data, 'value')).toBe('up');
+  });
+
+  it('returns "neutral" when yField is missing', () => {
+    expect(computeTrendFromData([{ a: 1 }, { a: 2 }], undefined)).toBe('neutral');
+  });
+
+  it('coerces string numbers and skips non-numeric values', () => {
+    const data = [{ v: '5' }, { v: 'not a number' }, { v: '4' }, { v: '3' }];
+    expect(computeTrendFromData(data, 'v')).toBe('down');
+  });
+});
+
+describe('trendColor', () => {
+  it('returns positive for up', () => {
+    expect(trendColor('up', baseTheme)).toBe('#16a34a');
+  });
+  it('returns negative for down', () => {
+    expect(trendColor('down', baseTheme)).toBe('#dc2626');
+  });
+  it('returns palette[0] for neutral', () => {
+    expect(trendColor('neutral', baseTheme)).toBe('#1b7fa3');
+  });
+});
+
+describe('hasExplicitColor', () => {
+  it('returns both false when markDef has no fill/stroke and no color encoding', () => {
+    expect(hasExplicitColor({ type: 'line' }, false)).toEqual({ fill: false, stroke: false });
+  });
+  it('returns fill=true when markDef.fill is set, leaves stroke false', () => {
+    expect(hasExplicitColor({ type: 'line', fill: '#ff00ff' } as MarkDef, false)).toEqual({
+      fill: true,
+      stroke: false,
+    });
+  });
+  it('returns stroke=true when markDef.stroke is set, leaves fill false', () => {
+    expect(hasExplicitColor({ type: 'line', stroke: '#ff00ff' } as MarkDef, false)).toEqual({
+      fill: false,
+      stroke: true,
+    });
+  });
+  it('returns both true when both markDef.fill and markDef.stroke are set', () => {
+    expect(
+      hasExplicitColor({ type: 'line', fill: '#ff00ff', stroke: '#00ffff' } as MarkDef, false),
+    ).toEqual({ fill: true, stroke: true });
+  });
+  it('returns both true when encoding.color is present (color scale drives both)', () => {
+    expect(hasExplicitColor({ type: 'line' }, true)).toEqual({ fill: true, stroke: true });
+  });
+});
+
+describe('buildSparklineAreaGradient', () => {
+  it('builds a top-to-bottom gradient with 0.35 -> 0 opacity in the trend color', () => {
+    const grad = buildSparklineAreaGradient('#16a34a');
+    expect(grad).toEqual({
+      gradient: 'linear',
+      x1: 0,
+      y1: 0,
+      x2: 0,
+      y2: 1,
+      stops: [
+        { offset: 0, color: '#16a34a', opacity: 0.35 },
+        { offset: 1, color: '#16a34a', opacity: 0 },
+      ],
+    });
+  });
+});

package/src/compiler/normalize.ts

@@ -63,11 +63,13 @@ function normalizeChromeField(value: string | ChromeText | undefined): ChromeTex
 function normalizeChrome(chrome: Chrome | undefined): NormalizedChrome {
   if (!chrome) return {};
   return {
+    eyebrow: normalizeChromeField(chrome.eyebrow),
     title: normalizeChromeField(chrome.title),
     subtitle: normalizeChromeField(chrome.subtitle),
     source: normalizeChromeField(chrome.source),
     byline: normalizeChromeField(chrome.byline),
     footer: normalizeChromeField(chrome.footer),
+    brand: normalizeChromeField(chrome.brand),
   };
 }
 
@@ -241,9 +243,11 @@ function normalizeChartSpec(spec: ChartSpec, warnings: string[]): NormalizedChar
     data: spec.data,
     encoding,
     chrome: normalizeChrome(spec.chrome),
+    metrics: spec.metrics,
     annotations: normalizeAnnotations(spec.annotations),
     labels: normalizeLabels(spec.labels),
     legend: spec.legend,
+    endpointLabels: spec.endpointLabels,
     responsive: spec.responsive ?? true,
     theme: spec.theme ?? {},
     darkMode: spec.darkMode ?? 'off',
@@ -256,6 +260,7 @@ function normalizeChartSpec(spec: ChartSpec, warnings: string[]): NormalizedChar
     userExplicit: {
       chrome: false,
       legend: false,
+      endpointLabels: false,
       xAxis: false,
       yAxis: false,
       labels: false,
@@ -463,6 +468,7 @@ export function flattenLayers(
   parentEncoding?: Encoding,
   parentTransforms?: import('@opendata-ai/openchart-core').Transform[],
   parentWatermark?: boolean,
+  parentEndpointLabels?: boolean | import('@opendata-ai/openchart-core').EndpointLabelsConfig,
 ): ChartSpec[] {
   const resolvedData = spec.data ?? parentData;
   const resolvedEncoding: Encoding | undefined =
@@ -472,6 +478,7 @@ export function flattenLayers(
   const resolvedTransforms = [...(parentTransforms ?? []), ...(spec.transform ?? [])];
   // Layer-level watermark propagates to children (child can still override)
   const resolvedWatermark = spec.watermark ?? parentWatermark;
+  const resolvedEndpointLabels = spec.endpointLabels ?? parentEndpointLabels;
 
   const leaves: ChartSpec[] = [];
 
@@ -485,6 +492,7 @@ export function flattenLayers(
           resolvedEncoding,
           resolvedTransforms,
           resolvedWatermark,
+          resolvedEndpointLabels,
         ),
       );
     } else {
@@ -504,7 +512,10 @@ export function flattenLayers(
         ...(child.watermark === undefined && resolvedWatermark !== undefined
           ? { watermark: resolvedWatermark }
           : {}),
-      });
+        ...(child.endpointLabels === undefined && resolvedEndpointLabels !== undefined
+          ? { endpointLabels: resolvedEndpointLabels }
+          : {}),
+      } as ChartSpec);
     }
   }
 

package/src/compiler/sparkline-defaults.ts

@@ -0,0 +1,138 @@
+/**
+ * Sparkline default resolution.
+ *
+ * When `display: 'sparkline'` is set on a chart spec, the engine fills in
+ * "smart" defaults so a minimal spec (mark + data + encoding) renders the
+ * polished mock-quality output without manual color, gradient, or endpoint
+ * configuration. Every default backs off when the user has set the
+ * corresponding field explicitly.
+ *
+ * Two public helpers:
+ * - {@link computeTrend} reads a value series and decides up/down/neutral
+ *   using a least-squares slope with a relative deadband. Naive
+ *   `last - first` would mislabel noisy series; this is more honest.
+ * - {@link resolveSparklineFill} picks the trend color, respecting the
+ *   precedence ladder: explicit `markDef.fill` > `encoding.color` >
+ *   theme override > sparkline trend default.
+ */
+
+import type { DataRow, GradientDef, MarkDef, ResolvedTheme } from '@opendata-ai/openchart-core';
+
+/** Trend classification for a single value series. */
+export type Trend = 'up' | 'down' | 'neutral';
+
+/**
+ * Relative slope below this magnitude reads as "no meaningful trend" and
+ * falls into the neutral bucket. 0.0005 = 0.05% of the series mean per step,
+ * which means a 20-point series needs roughly a 1% net change to register
+ * as a real trend. Tuned so financial sparklines (which often show 2-10%
+ * swings) reliably pick up trend color, while heavy noise around a flat
+ * mean still classifies as neutral.
+ */
+const TREND_DEADBAND = 0.0005;
+
+/**
+ * Decide whether a numeric series trends up, down, or neutral.
+ *
+ * Uses ordinary least-squares slope across the series, normalized by the
+ * absolute mean so the deadband applies consistently to series of any
+ * magnitude. Non-finite values are dropped before fitting; series with
+ * fewer than two finite points return 'neutral'.
+ */
+export function computeTrend(values: readonly number[]): Trend {
+  const finite: number[] = [];
+  for (const v of values) {
+    if (Number.isFinite(v)) finite.push(v);
+  }
+  if (finite.length < 2) return 'neutral';
+
+  const n = finite.length;
+  let sumX = 0;
+  let sumY = 0;
+  for (let i = 0; i < n; i++) {
+    sumX += i;
+    sumY += finite[i];
+  }
+  const meanX = sumX / n;
+  const meanY = sumY / n;
+
+  let num = 0;
+  let den = 0;
+  for (let i = 0; i < n; i++) {
+    const dx = i - meanX;
+    num += dx * (finite[i] - meanY);
+    den += dx * dx;
+  }
+  if (den === 0) return 'neutral';
+
+  const slope = num / den;
+  const scale = Math.abs(meanY) || 1;
+  const relSlope = slope / scale;
+  if (Math.abs(relSlope) < TREND_DEADBAND) return 'neutral';
+  return relSlope > 0 ? 'up' : 'down';
+}
+
+/** Map a trend classification to a color from the resolved theme. */
+export function trendColor(trend: Trend, theme: ResolvedTheme): string {
+  if (trend === 'up') return theme.colors.positive;
+  if (trend === 'down') return theme.colors.negative;
+  return theme.colors.categorical[0];
+}
+
+/**
+ * Pull the y-channel values out of a data array and classify the trend.
+ * Returns 'neutral' if the field is missing or the series is too short.
+ */
+export function computeTrendFromData(data: readonly DataRow[], yField: string | undefined): Trend {
+  if (!yField) return 'neutral';
+  const values: number[] = [];
+  for (const row of data) {
+    const v = Number(row[yField]);
+    if (Number.isFinite(v)) values.push(v);
+  }
+  return computeTrend(values);
+}
+
+/**
+ * Channel-by-channel report of whether a spec's color is "user-explicit"
+ * for that channel — the trend default backs off only for the channels
+ * the user has set.
+ *
+ * Precedence ladder (most explicit first):
+ * 1. `markDef.fill` / `markDef.stroke` set on the spec — channel-specific
+ * 2. `encoding.color` field encoding (the data drives color, not trend)
+ *    backs off both channels because the color scale produces both
+ * 3. Sparkline trend default (returned when both flags are false)
+ */
+export function hasExplicitColor(
+  markDef: MarkDef | undefined,
+  encodingHasColor: boolean,
+): { fill: boolean; stroke: boolean } {
+  if (encodingHasColor) return { fill: true, stroke: true };
+  return {
+    fill: markDef?.fill !== undefined,
+    stroke: markDef?.stroke !== undefined,
+  };
+}
+
+/**
+ * Build the default area gradient for a sparkline area mark. Uses the
+ * trend-derived base color and fades top→bottom from 35% to 0% opacity.
+ *
+ * Coordinate system is normalized [0,1] relative to the mark bounding box,
+ * matching the existing `LinearGradient` shape used by user-authored
+ * gradients (see `examples/src/sparkline.stories.tsx` for prior art).
+ */
+export function buildSparklineAreaGradient(baseColor: string): GradientDef {
+  return {
+    gradient: 'linear',
+    x1: 0,
+    y1: 0,
+    x2: 0,
+    y2: 1,
+    stops: [
+      { offset: 0, color: baseColor, opacity: 0.35 },
+      { offset: 1, color: baseColor, opacity: 0 },
+    ],
+  };
+}

package/src/compiler/types.ts

@@ -39,11 +39,13 @@ import type { NormalizedTileMapSpec } from '../tilemap/types';
 
 /** Chrome with all string values normalized to ChromeText objects. */
 export interface NormalizedChrome {
+  eyebrow?: ChromeText;
   title?: ChromeText;
   subtitle?: ChromeText;
   source?: ChromeText;
   byline?: ChromeText;
   footer?: ChromeText;
+  brand?: ChromeText;
 }
 
 // ---------------------------------------------------------------------------
@@ -78,6 +80,8 @@ export interface UserExplicit {
   chrome: boolean;
   /** True if user wrote `legend`. */
   legend: boolean;
+  /** True if user wrote `endpointLabels`. */
+  endpointLabels: boolean;
   /** True if user wrote `encoding.x.axis`. */
   xAxis: boolean;
   /** True if user wrote `encoding.y.axis`. */
@@ -101,12 +105,16 @@ export interface NormalizedChartSpec {
   data: DataRow[];
   encoding: Encoding;
   chrome: NormalizedChrome;
+  /** Optional KPI metric cells, passed through unchanged. */
+  metrics?: import('@opendata-ai/openchart-core').Metric[];
   annotations: Annotation[];
   /** Normalized label configuration with defaults applied. density, format, and prefix are always set; offsets and color stay optional. */
   labels: Required<Pick<LabelConfig, 'density' | 'format' | 'prefix'>> &
     Pick<LabelConfig, 'offsets' | 'color'>;
   /** Legend configuration (position override). */
   legend?: LegendConfig;
+  /** Right-side endpoint labels column config (multi-series line/area only). */
+  endpointLabels?: boolean | import('@opendata-ai/openchart-core').EndpointLabelsConfig;
   responsive: boolean;
   theme: ThemeConfig;
   darkMode: DarkMode;