@opendata-ai/openchart-engine 6.26.0 → 6.27.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as _opendata_ai_openchart_core from '@opendata-ai/openchart-core';
-import { LegendLayout, ResolvedChrome, TooltipContent, A11yMetadata, ResolvedTheme, CompileOptions, ChartLayout, LayerSpec, CompileTableOptions, TableLayout, AnimationSpec, ResolvedAnimation, TileMapEncoding, TileMapPalette, LegendConfig, ThemeConfig, DarkMode, MarkType, MarkDef, DataRow, Encoding, ChromeText, Annotation, LabelConfig, ColumnConfig, GraphSpec, GraphEncoding, GraphLayoutConfig, NodeOverride, SankeyEncoding, SankeyNodeAlign, SankeyLinkColor, VizSpec, ScaleType, EncodingChannel, Rect, LayoutStrategy, Mark, BinTransform, CalculateTransform, ConditionalValueDef, FilterPredicate, TimeUnitTransform, Transform } from '@opendata-ai/openchart-core';
+import { LegendLayout, ResolvedChrome, TooltipContent, A11yMetadata, ResolvedTheme, CompileOptions, ChartLayout, LayerSpec, CompileTableOptions, TableLayout, AnimationSpec, ResolvedAnimation, TileMapEncoding, TileMapPalette, LegendConfig, ThemeConfig, DarkMode, MarkType, MarkDef, DataRow, Encoding, ChromeText, Annotation, LabelConfig, Display, ColumnConfig, GraphSpec, GraphEncoding, GraphLayoutConfig, NodeOverride, SankeyEncoding, SankeyNodeAlign, SankeyLinkColor, VizSpec, ScaleType, EncodingChannel, Rect, LayoutStrategy, Mark, BinTransform, CalculateTransform, ConditionalValueDef, FilterPredicate, TimeUnitTransform, Transform } from '@opendata-ai/openchart-core';
 export { ChartLayout, ChartSpec, CompileOptions, CompileTableOptions, GraphLayout, GraphSpec, LayerSpec, SankeyLayout, SankeySpec, TableLayout, TableSpec, TileMapLayout, TileMapSpec, VizSpec } from '@opendata-ai/openchart-core';
 import { ScaleLinear, ScaleTime, ScaleLogarithmic, ScalePower, ScaleSymLog, ScaleBand, ScalePoint, ScaleOrdinal, ScaleQuantile, ScaleQuantize, ScaleThreshold } from 'd3-scale';
 
@@ -232,6 +232,34 @@ interface NormalizedChrome {
     byline?: ChromeText;
     footer?: ChromeText;
 }
+/**
+ * Tracks which top-level fields the user explicitly set in their input spec.
+ *
+ * Built from the raw expandedSpec (post-breakpoint-merge, pre-normalize) so
+ * that "user wrote chrome.title" vs "user wrote nothing" is distinguishable
+ * after normalization fills in defaults.
+ *
+ * Used by sparkline display mode to decide whether to suppress chrome/axes/
+ * legend/etc. by default vs. respecting an explicit user opt-in.
+ */
+interface UserExplicit {
+    /** True if user wrote `chrome` (any non-empty chrome). */
+    chrome: boolean;
+    /** True if user wrote `legend`. */
+    legend: boolean;
+    /** True if user wrote `encoding.x.axis`. */
+    xAxis: boolean;
+    /** True if user wrote `encoding.y.axis`. */
+    yAxis: boolean;
+    /** True if user wrote `labels`. */
+    labels: boolean;
+    /** True if user wrote `animation`. */
+    animation: boolean;
+    /** True if user wrote `watermark`. */
+    watermark: boolean;
+    /** True if user wrote `crosshair`. */
+    crosshair: boolean;
+}
 /** A ChartSpec with all optional fields filled with sensible defaults. */
 interface NormalizedChartSpec {
     /** Resolved mark type string (extracted from spec.mark). */
@@ -255,6 +283,14 @@ interface NormalizedChartSpec {
     hiddenSeries: string[];
     /** Per-series visual style overrides. */
     seriesStyles: Record<string, _opendata_ai_openchart_core.SeriesStyle>;
+    /** Display mode controlling chrome/axes/legend stripping. Defaults to `'full'`. */
+    display: Display;
+    /**
+     * Which top-level fields the user explicitly set. Populated by compileChart
+     * from the raw expanded spec before normalization. NormalizeChartSpec runs
+     * with a default-empty descriptor; compileChart overwrites it post-normalize.
+     */
+    userExplicit: UserExplicit;
 }
 /** A TableSpec with all optional fields filled with sensible defaults. */
 interface NormalizedTableSpec {

package/dist/index.js

@@ -5351,7 +5351,7 @@ function computeSingleArea(spec, scales, _chartArea) {
       fill: fillValue,
       fillOpacity,
       stroke: getRepresentativeColor4(isGradientDef3(fillValue) ? color2 : fillValue),
-      strokeWidth: 2,
+      strokeWidth: spec.display === "sparkline" ? 1.25 : 2,
       seriesKey: seriesKey === "__default__" ? void 0 : seriesKey,
       data: validPoints.map((p) => p.row),
       dataPoints: validPoints.map((p) => ({ x: p.x, y: p.yTop, datum: p.row })),
@@ -5468,6 +5468,7 @@ function computeAreaMarks(spec, scales, chartArea) {
 // src/charts/line/compute.ts
 import { getRepresentativeColor as getRepresentativeColor5 } from "@opendata-ai/openchart-core";
 var DEFAULT_STROKE_WIDTH = 2.5;
+var SPARKLINE_STROKE_WIDTH = 1.25;
 var DEFAULT_POINT_RADIUS = 3;
 function computeLineMarks(spec, scales, _chartArea, _strategy) {
   const encoding = spec.encoding;
@@ -5534,7 +5535,7 @@ function computeLineMarks(spec, scales, _chartArea, _strategy) {
       points: allPoints,
       path: combinedPath,
       stroke: strokeColor,
-      strokeWidth: styleOverride?.strokeWidth ?? DEFAULT_STROKE_WIDTH,
+      strokeWidth: styleOverride?.strokeWidth ?? (spec.display === "sparkline" ? SPARKLINE_STROKE_WIDTH : DEFAULT_STROKE_WIDTH),
       strokeDasharray,
       opacity: styleOverride?.opacity,
       seriesKey: seriesStyleKey,
@@ -6812,6 +6813,12 @@ function normalizeChartSpec(spec, warnings) {
   const encoding = inferEncodingTypes(spec.encoding, spec.data, warnings);
   const markType = resolveMarkType(spec.mark);
   const markDef = resolveMarkDef(spec.mark);
+  const display = spec.display ?? "full";
+  if (display === "sparkline" && markType !== "line" && markType !== "area" && markType !== "bar" && markType !== "point") {
+    warnings.push(
+      `[openchart] display: 'sparkline' works best with mark: 'line' | 'area' | 'bar' | 'point'. Got mark: '${markType}' \u2014 rendering may degrade.`
+    );
+  }
   return {
     markType,
     markDef,
@@ -6826,7 +6833,20 @@ function normalizeChartSpec(spec, warnings) {
     darkMode: spec.darkMode ?? "off",
     hiddenSeries: spec.hiddenSeries ?? [],
     seriesStyles: spec.seriesStyles ?? {},
-    watermark: spec.watermark ?? true
+    watermark: spec.watermark ?? true,
+    display,
+    // Default empty userExplicit; compileChart overwrites this with the real
+    // descriptor built from the raw expanded spec before normalize runs.
+    userExplicit: {
+      chrome: false,
+      legend: false,
+      xAxis: false,
+      yAxis: false,
+      labels: false,
+      animation: false,
+      watermark: false,
+      crosshair: false
+    }
   };
 }
 function normalizeTableSpec(spec, _warnings) {
@@ -8473,7 +8493,7 @@ function computeAxes(scales, chartArea, strategy, theme, measureText, dataContex
   };
   const { fontSize } = tickLabelStyle;
   const { fontWeight } = tickLabelStyle;
-  if (scales.x) {
+  if (scales.x && !dataContext?.skipX) {
     const axisConfig = scales.x.channel.axis;
     const isContinuousX = scales.x.type !== "band" && scales.x.type !== "point" && scales.x.type !== "ordinal";
     const xTargetCount = isContinuousX ? targetTickCount(chartArea.width, xDensity, "x") : void 0;
@@ -8551,7 +8571,7 @@ function computeAxes(scales, chartArea, strategy, theme, measureText, dataContex
       labelFlush: axisConfig?.labelFlush
     };
   }
-  if (scales.y) {
+  if (scales.y && !dataContext?.skipY) {
     const axisConfig = scales.y.channel.axis;
     const isContinuousY = scales.y.type !== "band" && scales.y.type !== "point" && scales.y.type !== "ordinal";
     const yTargetCount = isContinuousY ? targetTickCount(chartArea.height, yDensity, "y") : void 0;
@@ -8703,12 +8723,24 @@ function scalePadding(basePadding, width, height) {
 }
 var MIN_CHART_WIDTH = 60;
 var MIN_CHART_HEIGHT = 40;
+function getMinChartDims(display) {
+  return display === "sparkline" ? { width: 30, height: 20 } : { width: MIN_CHART_WIDTH, height: MIN_CHART_HEIGHT };
+}
+function getSparklinePad(spec) {
+  const strokeWidth = spec.markDef.strokeWidth ?? 2;
+  return Math.max(strokeWidth / 2 + 1, 2);
+}
 function computeDimensions(spec, options, legendLayout, theme, strategy, watermark = true) {
   const { width, height } = options;
   const padding = scalePadding(theme.spacing.padding, width, height);
   const hPad = width < BREAKPOINT_COMPACT_MAX ? Math.max(Math.round(padding * HPAD_COMPACT_FRACTION), HPAD_COMPACT_MIN) : padding;
   const axisMargin = theme.spacing.axisMargin;
-  const chromeMode = strategy?.chromeMode ?? "full";
+  const userExplicit = spec.userExplicit;
+  const isSparkline = spec.display === "sparkline";
+  let chromeMode = strategy?.chromeMode ?? "full";
+  if (isSparkline && !userExplicit.chrome) {
+    chromeMode = "hidden";
+  }
   const chrome = computeChrome2(
     chromeToInput(spec.chrome),
     theme,
@@ -8718,6 +8750,35 @@ function computeDimensions(spec, options, legendLayout, theme, strategy, waterma
     padding,
     watermark
   );
+  if (isSparkline) {
+    const total2 = { x: 0, y: 0, width, height };
+    const sparkPad = getSparklinePad(spec);
+    const xAxisSpace = userExplicit.xAxis ? 26 : 0;
+    const yAxisSpace = userExplicit.yAxis ? 30 : 0;
+    const margins2 = {
+      top: chrome.topHeight + sparkPad,
+      right: sparkPad,
+      bottom: chrome.bottomHeight + sparkPad + xAxisSpace,
+      left: sparkPad + yAxisSpace
+    };
+    if (userExplicit.legend && "entries" in legendLayout && legendLayout.entries.length > 0) {
+      const gap = legendGap(width);
+      if (legendLayout.position === "right" || legendLayout.position === "bottom-right") {
+        margins2.right += legendLayout.bounds.width + 8;
+      } else if (legendLayout.position === "top") {
+        margins2.top += legendLayout.bounds.height + gap;
+      } else if (legendLayout.position === "bottom") {
+        margins2.bottom += legendLayout.bounds.height + gap;
+      }
+    }
+    const chartArea2 = {
+      x: margins2.left,
+      y: margins2.top,
+      width: Math.max(0, width - margins2.left - margins2.right),
+      height: Math.max(0, height - margins2.top - margins2.bottom)
+    };
+    return { total: total2, chrome, chartArea: chartArea2, margins: margins2, theme };
+  }
   const total = { x: 0, y: 0, width, height };
   const isRadial = spec.markType === "arc";
   const encoding = spec.encoding;
@@ -8891,7 +8952,8 @@ function computeDimensions(spec, options, legendLayout, theme, strategy, waterma
     width: Math.max(0, width - margins.left - margins.right),
     height: Math.max(0, height - margins.top - margins.bottom)
   };
-  if ((chartArea.width < MIN_CHART_WIDTH || chartArea.height < MIN_CHART_HEIGHT) && chromeMode !== "hidden") {
+  const minDims = getMinChartDims(spec.display);
+  if ((chartArea.width < minDims.width || chartArea.height < minDims.height) && chromeMode !== "hidden") {
     const fallbackMode = chromeMode === "full" ? "compact" : "hidden";
     const fallbackChrome = computeChrome2(
       chromeToInput(spec.chrome),
@@ -9438,7 +9500,8 @@ function truncateEntries(entries, maxCount) {
   return truncated;
 }
 function computeLegend(spec, strategy, theme, chartArea, watermark = true) {
-  if (spec.legend?.show === false || strategy.legendMaxHeight === 0) {
+  const sparklineHidden = spec.display === "sparkline" && !spec.userExplicit.legend;
+  if (sparklineHidden || spec.legend?.show === false || strategy.legendMaxHeight === 0) {
     return {
       position: "top",
       entries: [],
@@ -12176,7 +12239,7 @@ function compileChart(spec, options) {
   }
   let chartSpec = normalized;
   const rawWatermark = expandedSpec.watermark;
-  const watermark = rawWatermark !== void 0 ? chartSpec.watermark : options.watermark ?? true;
+  let watermark = rawWatermark !== void 0 ? chartSpec.watermark : options.watermark ?? true;
   const rawTransforms = expandedSpec.transform;
   if (rawTransforms && rawTransforms.length > 0) {
     chartSpec = { ...chartSpec, data: runTransforms(chartSpec.data, rawTransforms) };
@@ -12186,6 +12249,21 @@ function compileChart(spec, options) {
   let strategy = getLayoutStrategy(breakpoint, heightClass);
   const rawSpec = expandedSpec;
   const overrides = rawSpec.overrides;
+  const rawEncoding = rawSpec.encoding;
+  const bpForExplicit = overrides?.[breakpoint];
+  const bpEncoding = bpForExplicit?.encoding;
+  const hasChromeKeys = (v) => !!v && typeof v === "object" && Object.keys(v).length > 0;
+  const userExplicit = {
+    chrome: hasChromeKeys(rawSpec.chrome) || hasChromeKeys(bpForExplicit?.chrome),
+    legend: rawSpec.legend !== void 0 || bpForExplicit?.legend !== void 0,
+    xAxis: rawEncoding?.x?.axis !== void 0 || bpEncoding?.x?.axis !== void 0,
+    yAxis: rawEncoding?.y?.axis !== void 0 || bpEncoding?.y?.axis !== void 0,
+    labels: rawSpec.labels !== void 0 || bpForExplicit?.labels !== void 0,
+    animation: rawSpec.animation !== void 0 || bpForExplicit?.animation !== void 0,
+    watermark: rawSpec.watermark !== void 0 || bpForExplicit?.watermark !== void 0,
+    crosshair: rawSpec.crosshair !== void 0 || bpForExplicit?.crosshair !== void 0
+  };
+  chartSpec = { ...chartSpec, userExplicit };
   if (overrides?.[breakpoint]) {
     const bp = overrides[breakpoint];
     if (bp.chrome) {
@@ -12229,9 +12307,80 @@ function compileChart(spec, options) {
       };
       strategy = { ...strategy, annotationPosition: "inline" };
     }
+    if (bp.display !== void 0) {
+      chartSpec = {
+        ...chartSpec,
+        display: bp.display
+      };
+    }
+    if (bp.encoding !== void 0) {
+      const bpEnc = bp.encoding;
+      const mergedEncoding = { ...chartSpec.encoding };
+      const NESTED_CHANNEL_KEYS = ["axis", "scale"];
+      for (const channel of Object.keys(bpEnc)) {
+        const baseCh = mergedEncoding[channel];
+        const bpCh = bpEnc[channel];
+        if (bpCh && baseCh) {
+          const merged = { ...baseCh, ...bpCh };
+          for (const key of NESTED_CHANNEL_KEYS) {
+            const baseNested = baseCh[key];
+            const bpNested = bpCh[key];
+            if (baseNested && bpNested && typeof baseNested === "object" && typeof bpNested === "object" && !Array.isArray(baseNested) && !Array.isArray(bpNested)) {
+              merged[key] = { ...baseNested, ...bpNested };
+            }
+          }
+          mergedEncoding[channel] = merged;
+        } else if (bpCh) {
+          mergedEncoding[channel] = bpCh;
+        }
+      }
+      chartSpec = {
+        ...chartSpec,
+        encoding: mergedEncoding
+      };
+    }
+    if (typeof bp.watermark === "boolean") {
+      watermark = bp.watermark;
+      chartSpec = { ...chartSpec, watermark };
+    }
+  }
+  if (chartSpec.display === "sparkline" && !chartSpec.userExplicit.labels) {
+    chartSpec = {
+      ...chartSpec,
+      labels: { ...chartSpec.labels, density: "none" }
+    };
+  }
+  let rawAnimationSpec = overrides?.[breakpoint]?.animation ?? rawSpec.animation;
+  if (rawAnimationSpec === void 0 && chartSpec.display === "sparkline") {
+    rawAnimationSpec = false;
+  }
+  if (chartSpec.display === "sparkline" && rawAnimationSpec !== false && rawAnimationSpec !== void 0) {
+    const SPARK_DURATION = 1100;
+    if (rawAnimationSpec === true) {
+      rawAnimationSpec = { enter: { duration: SPARK_DURATION } };
+    } else if (typeof rawAnimationSpec === "object") {
+      const cfg = rawAnimationSpec;
+      const enter = cfg.enter;
+      if (enter === void 0 || enter === true) {
+        rawAnimationSpec = {
+          ...cfg,
+          enter: { duration: SPARK_DURATION }
+        };
+      } else if (typeof enter === "object" && enter !== null && enter.duration === void 0) {
+        rawAnimationSpec = {
+          ...cfg,
+          enter: { ...enter, duration: SPARK_DURATION }
+        };
+      }
+    }
   }
-  const rawAnimationSpec = overrides?.[breakpoint]?.animation ?? rawSpec.animation;
   const resolvedAnimation = resolveAnimation(rawAnimationSpec);
+  const rawCrosshair = bpForExplicit?.crosshair ?? rawSpec.crosshair;
+  const crosshair = chartSpec.display === "sparkline" && !chartSpec.userExplicit.crosshair ? false : rawCrosshair === true;
+  if (chartSpec.display === "sparkline" && !chartSpec.userExplicit.watermark) {
+    watermark = false;
+    chartSpec = { ...chartSpec, watermark: false };
+  }
   const mergedThemeConfig = options.theme ? { ...chartSpec.theme, ...options.theme } : chartSpec.theme;
   let theme = resolveTheme4(mergedThemeConfig);
   if (options.darkMode) {
@@ -12276,9 +12425,13 @@ function compileChart(spec, options) {
   applyColorScaleRange(scales, renderSpec.encoding, theme);
   scales.defaultColor = chartSpec.markDef.fill ?? chartSpec.markDef.stroke ?? theme.colors.categorical[0];
   const isRadial = chartSpec.markType === "arc";
+  const skipX = chartSpec.display === "sparkline" && !chartSpec.userExplicit.xAxis;
+  const skipY = chartSpec.display === "sparkline" && !chartSpec.userExplicit.yAxis;
   const axes = isRadial ? { x: void 0, y: void 0 } : computeAxes(scales, chartArea, strategy, theme, options.measureText, {
     data: renderSpec.data,
-    encoding: renderSpec.encoding
+    encoding: renderSpec.encoding,
+    skipX,
+    skipY
   });
   if (!isRadial) {
     computeGridlines(axes, chartArea);
@@ -12354,6 +12507,8 @@ function compileChart(spec, options) {
     },
     animation: resolvedAnimation,
     watermark,
+    display: chartSpec.display,
+    crosshair,
     measureText: options.measureText
   };
 }