@opendata-ai/openchart-engine 6.26.0 → 6.27.2

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

@@ -3692,6 +3692,22 @@ function resolvePosition(value2, scale) {
   }
   return null;
 }
+function resolvePositionEdge(value2, scale, edge) {
+  const center2 = resolvePosition(value2, scale);
+  if (center2 === null || !scale) return null;
+  const type = scale.type;
+  if (type === "point") {
+    const s = scale.scale;
+    const halfStep = (s.step?.() ?? 0) / 2;
+    return edge === "start" ? center2 - halfStep : center2 + halfStep;
+  }
+  if (type === "band") {
+    const s = scale.scale;
+    const halfBw = (s.bandwidth?.() ?? 0) / 2;
+    return edge === "start" ? center2 - halfBw : center2 + halfBw;
+  }
+  return center2;
+}
 
 // src/annotations/collisions.ts
 function generateNudgeCandidates(selfBounds, obstacles, padding) {
@@ -3924,15 +3940,15 @@ function resolveRangeAnnotation(annotation, scales, chartArea, isDark) {
   let width = chartArea.width;
   let height = chartArea.height;
   if (annotation.x1 !== void 0 && annotation.x2 !== void 0) {
-    const x1px = resolvePosition(annotation.x1, scales.x);
-    const x2px = resolvePosition(annotation.x2, scales.x);
+    const x1px = resolvePositionEdge(annotation.x1, scales.x, "start");
+    const x2px = resolvePositionEdge(annotation.x2, scales.x, "end");
     if (x1px === null || x2px === null) return null;
     x2 = Math.min(x1px, x2px);
     width = Math.abs(x2px - x1px);
   }
   if (annotation.y1 !== void 0 && annotation.y2 !== void 0) {
-    const y1px = resolvePosition(annotation.y1, scales.y);
-    const y2px = resolvePosition(annotation.y2, scales.y);
+    const y1px = resolvePositionEdge(annotation.y1, scales.y, "end");
+    const y2px = resolvePositionEdge(annotation.y2, scales.y, "start");
     if (y1px === null || y2px === null) return null;
     y2 = Math.min(y1px, y2px);
     height = Math.abs(y2px - y1px);
@@ -5351,7 +5367,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 +5484,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 +5551,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 +6829,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 +6849,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) {
@@ -8213,9 +8249,9 @@ import {
   formatNumber as formatNumber2
 } from "@opendata-ai/openchart-core";
 var Y_PX_PER_TICK = {
-  full: 55,
-  reduced: 90,
-  minimal: 140
+  full: 40,
+  reduced: 70,
+  minimal: 120
 };
 var X_PX_PER_TICK = {
   full: 110,
@@ -8293,7 +8329,21 @@ function buildContinuousTicks(resolvedScale, count) {
     return continuousTicks(resolvedScale, "full");
   }
   const raw = scale.ticks(count);
-  return raw.map((value2) => ({
+  let ticks2 = raw;
+  if (resolvedScale.type === "log" && raw.length > count) {
+    const base = resolvedScale.channel.scale?.base ?? 10;
+    const logBase = Math.log(base);
+    const powered = raw.filter((v) => {
+      const n = v;
+      if (n <= 0) return false;
+      const exp = Math.log(n) / logBase;
+      return Math.abs(exp - Math.round(exp)) < 1e-9;
+    });
+    if (powered.length >= 2) {
+      ticks2 = powered;
+    }
+  }
+  return ticks2.map((value2) => ({
     value: value2,
     position: scale(value2),
     label: formatTickLabel(value2, resolvedScale)
@@ -8396,8 +8446,8 @@ function resolveExplicitTicks(values, resolvedScale) {
 }
 
 // src/layout/axes.ts
-var HEIGHT_MINIMAL_THRESHOLD = 120;
-var HEIGHT_REDUCED_THRESHOLD = 200;
+var HEIGHT_MINIMAL_THRESHOLD = 80;
+var HEIGHT_REDUCED_THRESHOLD = 100;
 var WIDTH_MINIMAL_THRESHOLD = 150;
 var WIDTH_REDUCED_THRESHOLD = 300;
 var DENSITY_ORDER = ["full", "reduced", "minimal"];
@@ -8473,7 +8523,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 +8601,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 +8753,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 +8780,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 +8982,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 +9530,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 +12269,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 +12279,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 +12337,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 +12455,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 +12537,8 @@ function compileChart(spec, options) {
     },
     animation: resolvedAnimation,
     watermark,
+    display: chartSpec.display,
+    crosshair,
     measureText: options.measureText
   };
 }