@opendata-ai/openchart-engine 6.28.6 → 7.0.0

package/src/annotations/resolve-text.ts

@@ -3,24 +3,40 @@
  * optional callout connector to the data point.
  */
 
-import type {
-  Rect,
-  ResolvedAnnotation,
-  ResolvedLabel,
-  TextAnnotation,
-  TextStyle,
+import {
+  estimateTextWidth,
+  type Rect,
+  type ResolvedAnnotation,
+  type ResolvedLabel,
+  type TextAnnotation,
+  type TextStyle,
 } from '@opendata-ai/openchart-core';
 import type { ResolvedScales } from '../layout/scales';
 import {
+  DARK_DOT_FILL,
+  DARK_MUTED_TEXT_FILL,
   DARK_TEXT_FILL,
   DEFAULT_ANNOTATION_FONT_SIZE,
   DEFAULT_ANNOTATION_FONT_WEIGHT,
+  DEFAULT_DOT_RADIUS,
+  DEFAULT_DOT_STROKE_WIDTH,
   DEFAULT_LINE_HEIGHT,
+  LIGHT_DOT_FILL,
+  LIGHT_MUTED_TEXT_FILL,
   LIGHT_TEXT_FILL,
+  SUBTITLE_FONT_SIZE_RATIO,
+  SUBTITLE_GAP,
 } from './constants';
 import { applyOffset, computeAnchorOffset, computeConnectorOrigin } from './geometry';
 import { resolvePosition } from './position';
 
+/** Horizontal gap between the drop-line and the label text. */
+const DROP_LINE_LABEL_GAP = 8;
+/** Vertical gap between the top of the drop-line and the top of the label box. */
+const DROP_LINE_TOP_GAP = 4;
+/** Vertical gap between the bottom of the drop-line and the data point. */
+const DROP_LINE_BOTTOM_GAP = 4;
+
 export function makeAnnotationLabelStyle(
   fontSize?: number,
   fontWeight?: number,
@@ -58,6 +74,13 @@ export function resolveTextAnnotation(
     isDark,
   );
 
+  // Drop-line connector: vertical line through the data point's x with the
+  // label sitting flush beside it. Auto-flips to the opposite side if the
+  // chosen side would overflow the chart area.
+  if (annotation.connector === 'drop-line') {
+    return resolveDropLineAnnotation(annotation, px, py, chartArea, labelStyle, defaultTextFill);
+  }
+
   // Compute position from anchor direction + user offset
   const anchorDelta = computeAnchorOffset(annotation.anchor, px, py, chartArea);
   const finalDelta = applyOffset(anchorDelta, annotation.offset);
@@ -67,7 +90,8 @@ export function resolveTextAnnotation(
 
   // Connector: draw unless explicitly disabled
   const showConnector = annotation.connector !== false;
-  const connectorStyle = annotation.connector === 'curve' ? 'curve' : 'straight';
+  const connectorStyle: 'straight' | 'curve' =
+    annotation.connector === 'curve' ? 'curve' : 'straight';
 
   // Compute connector origin: pick the edge midpoint closest to the data point
   const fontSize = annotation.fontSize ?? DEFAULT_ANNOTATION_FONT_SIZE;
@@ -116,6 +140,7 @@ export function resolveTextAnnotation(
       ? {
           from: adjustedFrom,
           to: adjustedTo,
+          endpoint: { x: px, y: py },
           stroke: annotation.stroke ?? '#999999',
           style: connectorStyle,
         }
@@ -124,6 +149,135 @@ export function resolveTextAnnotation(
     halo: annotation.halo,
   };
 
+  // Resolve dot marker. Uses the connector's "to" endpoint coordinates
+  // (post user-supplied connectorOffset.to) so it sits exactly where the
+  // connector terminates at the data point.
+  let dot: ResolvedAnnotation['dot'] | undefined;
+  if (annotation.dot) {
+    const dotConfig = typeof annotation.dot === 'object' ? annotation.dot : {};
+    const defaultDotFill = isDark ? DARK_DOT_FILL : LIGHT_DOT_FILL;
+    const defaultDotStroke = isDark ? DARK_TEXT_FILL : LIGHT_TEXT_FILL;
+    dot = {
+      x: adjustedTo.x,
+      y: adjustedTo.y,
+      radius: dotConfig.radius ?? DEFAULT_DOT_RADIUS,
+      fill: dotConfig.fill ?? defaultDotFill,
+      stroke: dotConfig.stroke ?? defaultDotStroke,
+      strokeWidth: dotConfig.strokeWidth ?? DEFAULT_DOT_STROKE_WIDTH,
+    };
+  }
+
+  // Resolve subtitle. Positioned below the primary text block by
+  // (lineHeight * primaryLineCount * fontSize) + gap.
+  let subtitle: ResolvedAnnotation['subtitle'] | undefined;
+  if (annotation.subtitle) {
+    const primaryLineCount = annotation.text.split('\n').length;
+    const subtitleFontSize = Math.round(fontSize * SUBTITLE_FONT_SIZE_RATIO);
+    const mutedFill = isDark ? DARK_MUTED_TEXT_FILL : LIGHT_MUTED_TEXT_FILL;
+    const subtitleStyle: TextStyle = {
+      ...labelStyle,
+      fontSize: subtitleFontSize,
+      fontWeight: DEFAULT_ANNOTATION_FONT_WEIGHT,
+      fill: mutedFill,
+    };
+    const subtitleY = labelY + fontSize * DEFAULT_LINE_HEIGHT * primaryLineCount + SUBTITLE_GAP;
+    subtitle = {
+      text: annotation.subtitle,
+      x: labelX,
+      y: subtitleY,
+      style: subtitleStyle,
+    };
+  }
+
+  return {
+    type: 'text',
+    id: annotation.id,
+    label,
+    stroke: annotation.stroke,
+    fill: annotation.fill,
+    opacity: annotation.opacity,
+    zIndex: annotation.zIndex,
+    dot,
+    subtitle,
+  };
+}
+
+/**
+ * Resolve a drop-line text annotation. The connector is a vertical line through
+ * the data point's x. The label sits beside the line, anchored toward the chosen
+ * side (left or right), and auto-flips if the chosen side would overflow.
+ */
+function resolveDropLineAnnotation(
+  annotation: TextAnnotation,
+  px: number,
+  py: number,
+  chartArea: Rect,
+  labelStyle: TextStyle,
+  defaultTextFill: string,
+): ResolvedAnnotation {
+  const fontSize = annotation.fontSize ?? DEFAULT_ANNOTATION_FONT_SIZE;
+  const fontWeight = annotation.fontWeight ?? DEFAULT_ANNOTATION_FONT_WEIGHT;
+  const lines = annotation.text.split('\n');
+  const estimatedWidth = Math.max(
+    0,
+    ...lines.map((line) => estimateTextWidth(line, fontSize, fontWeight)),
+  );
+
+  // Pick initial side from anchor; default to 'left' (label sits to the left
+  // of the drop-line) when not specified.
+  let side: 'left' | 'right' = annotation.anchor === 'right' ? 'right' : 'left';
+
+  // Auto-flip: if the chosen side would push the label past the chart-area edge,
+  // flip to the other side. Compare the estimated label width against the
+  // available space on each side. When neither side fits cleanly, fall back to
+  // whichever side has more room — graceful degradation beats silent overflow.
+  const spaceLeft = px - chartArea.x - DROP_LINE_LABEL_GAP;
+  const spaceRight = chartArea.x + chartArea.width - px - DROP_LINE_LABEL_GAP;
+  const fitsLeft = estimatedWidth <= spaceLeft;
+  const fitsRight = estimatedWidth <= spaceRight;
+  if (side === 'left' && !fitsLeft) {
+    side = fitsRight || spaceRight > spaceLeft ? 'right' : 'left';
+  } else if (side === 'right' && !fitsRight) {
+    side = fitsLeft || spaceLeft > spaceRight ? 'left' : 'right';
+  }
+
+  const labelX = side === 'left' ? px - DROP_LINE_LABEL_GAP : px + DROP_LINE_LABEL_GAP;
+  const textAnchor: 'start' | 'end' = side === 'left' ? 'end' : 'start';
+
+  // Drop the label box top a bit above the data point so the label and line
+  // share a baseline that reads as "callout above the point".
+  const lineHeight = fontSize * DEFAULT_LINE_HEIGHT;
+  const totalHeight = lineHeight * lines.length;
+  // Position the first line so the bottom of the label sits ~12px above py.
+  // Clamp to the chart-area top so multi-line labels near peaks don't escape
+  // upward into chrome / metric-bar territory.
+  const desiredLabelTopY = py - totalHeight - 12;
+  const minLabelTopY = chartArea.y + 4;
+  const labelTopY = Math.max(desiredLabelTopY, minLabelTopY);
+  const labelBaselineY = labelTopY + fontSize;
+
+  const resolvedStyle: TextStyle = { ...labelStyle, textAnchor };
+
+  const from = { x: px, y: labelTopY - DROP_LINE_TOP_GAP };
+  const to = { x: px, y: py - DROP_LINE_BOTTOM_GAP };
+
+  const label: ResolvedLabel = {
+    text: annotation.text,
+    x: labelX,
+    y: labelBaselineY,
+    style: resolvedStyle,
+    visible: true,
+    connector: {
+      from,
+      to,
+      endpoint: { x: px, y: py },
+      stroke: annotation.stroke ?? defaultTextFill,
+      style: 'drop-line',
+    },
+    background: annotation.background,
+    halo: annotation.halo,
+  };
+
   return {
     type: 'text',
     id: annotation.id,

package/src/charts/bar/compute.ts

@@ -372,6 +372,19 @@ function applyMarkDefOverrides(
 
   if (fixedSize == null && crSpec == null) return marks;
 
+  // Identify the rightmost segment per stackGroup (largest `x + width`).
+  // Only that segment receives the corner rounding so the seams between
+  // stacked segments stay square and flush.
+  const rightPerStack = new Map<string, RectMark>();
+  for (const mark of marks) {
+    if (mark.stackGroup === undefined) continue;
+    const current = rightPerStack.get(mark.stackGroup);
+    const markRight = mark.x + mark.width;
+    if (!current || markRight > current.x + current.width) {
+      rightPerStack.set(mark.stackGroup, mark);
+    }
+  }
+
   for (const mark of marks) {
     if (fixedSize != null && mark.stackGroup === undefined) {
       const barHeight = Math.min(fixedSize, bandwidth);
@@ -380,10 +393,21 @@ function applyMarkDefOverrides(
       mark.height = barHeight;
     }
     const effectiveHeight = mark.height;
+    const isStacked = mark.stackGroup !== undefined;
+    const isStackRight = isStacked && rightPerStack.get(mark.stackGroup!) === mark;
+
+    if (isStacked && !isStackRight) continue;
+
     if (crSpec === 'pill') {
       mark.cornerRadius = effectiveHeight / 2;
     } else if (typeof crSpec === 'number') {
       mark.cornerRadius = crSpec;
+    } else {
+      continue;
+    }
+
+    if (isStackRight) {
+      mark.cornerRadiusSides = { tl: false, tr: true, br: true, bl: false };
     }
   }
   return marks;

package/src/charts/bar/labels.ts

@@ -119,6 +119,7 @@ export function computeBarLabels(
     } else {
       // Fallback: extract from aria label
       const ariaLabel = mark.aria.label;
+      if (!ariaLabel) continue;
       const lastColon = ariaLabel.lastIndexOf(':');
       const rawValue = lastColon >= 0 ? ariaLabel.slice(lastColon + 1).trim() : '';
       if (!rawValue) continue;

package/src/charts/column/compute.ts

@@ -68,7 +68,14 @@ export function computeColumnMarks(
   }
 
   const bandwidth = xScale.bandwidth();
-  const baseline = yScale(0);
+  // Baseline = pixel y where the column's bottom edge anchors. When the
+  // y-domain includes zero (the common case), this is yScale(0). Sparkline
+  // mode tightens the domain to [min, max] (zero: false) so yScale(0) lands
+  // outside the chart area; in that case we anchor to the bottom of the
+  // y-range instead, otherwise every bar would render with the same height.
+  const yDomain = yScale.domain() as [number, number];
+  const yIncludesZero = yDomain[0] <= 0 && yDomain[1] >= 0;
+  const baseline = yIncludesZero ? yScale(0) : yScale(yDomain[0]);
   const colorEnc = encoding.color && 'field' in encoding.color ? encoding.color : undefined;
   const conditionalColor =
     encoding.color && isConditionalValueDef(encoding.color)
@@ -423,6 +430,18 @@ function applyMarkDefOverrides(
 
   if (fixedSize == null && crSpec == null) return marks;
 
+  // Identify the topmost segment per stackGroup (smallest `y` since SVG
+  // grows downward). Only that segment receives the corner rounding so
+  // the seams between stacked segments stay square and flush.
+  const topPerStack = new Map<string, RectMark>();
+  for (const mark of marks) {
+    if (mark.stackGroup === undefined) continue;
+    const current = topPerStack.get(mark.stackGroup);
+    if (!current || mark.y < current.y) {
+      topPerStack.set(mark.stackGroup, mark);
+    }
+  }
+
   for (const mark of marks) {
     if (fixedSize != null && mark.stackGroup === undefined) {
       const barWidth = Math.min(fixedSize, bandwidth);
@@ -431,10 +450,23 @@ function applyMarkDefOverrides(
       mark.width = barWidth;
     }
     const effectiveWidth = mark.width;
+    const isStacked = mark.stackGroup !== undefined;
+    const isStackTop = isStacked && topPerStack.get(mark.stackGroup!) === mark;
+
+    // Stacked segments below the top stay square. Stack top rounds only its
+    // top corners; non-stacked bars round all four.
+    if (isStacked && !isStackTop) continue;
+
     if (crSpec === 'pill') {
       mark.cornerRadius = effectiveWidth / 2;
     } else if (typeof crSpec === 'number') {
       mark.cornerRadius = crSpec;
+    } else {
+      continue;
+    }
+
+    if (isStackTop) {
+      mark.cornerRadiusSides = { tl: true, tr: true, br: false, bl: false };
     }
   }
 

package/src/charts/column/labels.ts

@@ -72,6 +72,7 @@ export function computeColumnLabels(
     } else {
       // Fallback: extract from aria label
       const ariaLabel = mark.aria.label;
+      if (!ariaLabel) continue;
       const lastColon = ariaLabel.lastIndexOf(':');
       const rawValue = lastColon >= 0 ? ariaLabel.slice(lastColon + 1).trim() : '';
       if (!rawValue) continue;

package/src/charts/dot/labels.ts

@@ -70,6 +70,7 @@ export function computeDotLabels(
     } else {
       // Fallback: extract from aria label
       const ariaLabel = mark.aria.label;
+      if (!ariaLabel) continue;
       const lastColon = ariaLabel.lastIndexOf(':');
       valuePart = lastColon >= 0 ? ariaLabel.slice(lastColon + 1).trim() : '';
       if (!valuePart) continue;

package/src/charts/line/__tests__/compute.test.ts

@@ -505,8 +505,9 @@ describe('computeAreaMarks', () => {
     }
   });
 
-  it('stacked areas: produces multiple AreaMarks for multi-series', () => {
+  it('stacked areas: produces multiple AreaMarks for multi-series with stack: "zero"', () => {
     const spec = makeMultiSeriesSpec();
+    spec.encoding.y!.stack = 'zero';
     const scales = computeScales(spec, chartArea, spec.data);
     const marks = computeAreaMarks(spec, scales, chartArea);
 
@@ -516,6 +517,129 @@ describe('computeAreaMarks', () => {
     expect(seriesKeys).toContain('UK');
   });
 
+  it('overlap (default): produces multiple AreaMarks for multi-series', () => {
+    // v6 default: multi-series with color but no `stack` overlaps instead of stacking.
+    const spec = makeMultiSeriesSpec();
+    const scales = computeScales(spec, chartArea, spec.data);
+    const marks = computeAreaMarks(spec, scales, chartArea);
+
+    expect(marks).toHaveLength(2);
+    const seriesKeys = marks.map((m) => m.seriesKey).filter(Boolean);
+    expect(seriesKeys).toContain('US');
+    expect(seriesKeys).toContain('UK');
+  });
+
+  it('overlap: every series shares the same baseline (no stacking offset)', () => {
+    const spec = makeMultiSeriesSpec();
+    const scales = computeScales(spec, chartArea, spec.data);
+    const marks = computeAreaMarks(spec, scales, chartArea);
+
+    // All bottom points across all series should be at the same baseline.
+    const baselines = new Set<number>();
+    for (const mark of marks) {
+      for (const p of mark.bottomPoints) {
+        baselines.add(p.y);
+      }
+    }
+    expect(baselines.size).toBe(1);
+  });
+
+  it('overlap: each series uses a translucent gradient fill', () => {
+    const spec = makeMultiSeriesSpec();
+    const scales = computeScales(spec, chartArea, spec.data);
+    const marks = computeAreaMarks(spec, scales, chartArea);
+
+    expect(marks.length).toBeGreaterThan(0);
+    for (const mark of marks) {
+      expect(typeof mark.fill).toBe('object');
+      const fill = mark.fill as { gradient: string; stops: { opacity?: number }[] };
+      expect(fill.gradient).toBe('linear');
+      // Overlap stops are calibrated lower than solo stops so layered bands stay legible.
+      expect(fill.stops[0].opacity).toBe(0.22);
+      expect(fill.stops[fill.stops.length - 1].opacity).toBe(0);
+    }
+  });
+
+  it('overlap: stack: null is treated the same as undefined (overlap)', () => {
+    const spec = makeMultiSeriesSpec();
+    spec.encoding.y!.stack = null;
+    const scales = computeScales(spec, chartArea, spec.data);
+    const marks = computeAreaMarks(spec, scales, chartArea);
+
+    expect(marks).toHaveLength(2);
+    // Same baseline -> overlap, not stacked
+    const baselines = new Set(marks.flatMap((m) => m.bottomPoints.map((p) => p.y)));
+    expect(baselines.size).toBe(1);
+  });
+
+  it('overlap: stack: false is treated the same as undefined (overlap)', () => {
+    const spec = makeMultiSeriesSpec();
+    spec.encoding.y!.stack = false;
+    const scales = computeScales(spec, chartArea, spec.data);
+    const marks = computeAreaMarks(spec, scales, chartArea);
+
+    expect(marks).toHaveLength(2);
+    const baselines = new Set(marks.flatMap((m) => m.bottomPoints.map((p) => p.y)));
+    expect(baselines.size).toBe(1);
+  });
+
+  it('stack: true opts into stacked rendering', () => {
+    const spec = makeMultiSeriesSpec();
+    spec.encoding.y!.stack = true;
+    const scales = computeScales(spec, chartArea, spec.data);
+    const marks = computeAreaMarks(spec, scales, chartArea);
+
+    expect(marks).toHaveLength(2);
+    // Stacked layers should have different baselines (one stacks on top of the other)
+    const firstBottom = marks[0].bottomPoints[0]?.y;
+    const secondBottom = marks[1].bottomPoints[0]?.y;
+    expect(firstBottom).not.toBe(secondBottom);
+  });
+
+  it('solo (single series) uses the richer solo gradient', () => {
+    const spec = makeSingleSeriesSpec();
+    const scales = computeScales(spec, chartArea, spec.data);
+    const marks = computeAreaMarks(spec, scales, chartArea);
+
+    expect(marks).toHaveLength(1);
+    const fill = marks[0].fill as { gradient: string; stops: { opacity?: number }[] };
+    expect(fill.gradient).toBe('linear');
+    // Solo stops are heavier than overlap stops since there's no overlap.
+    expect(fill.stops[0].opacity).toBe(0.42);
+  });
+
+  it('stacked areas use a top-to-bottom gradient fill (not flat opacity)', () => {
+    const spec = makeMultiSeriesSpec();
+    spec.encoding.y!.stack = 'zero';
+    const scales = computeScales(spec, chartArea, spec.data);
+    const marks = computeAreaMarks(spec, scales, chartArea);
+
+    expect(marks.length).toBeGreaterThan(0);
+    for (const mark of marks) {
+      const fill = mark.fill as { gradient: string; stops: { opacity?: number }[] };
+      expect(fill.gradient).toBe('linear');
+      expect(fill.stops).toHaveLength(2);
+      expect(fill.stops[0].opacity).toBe(0.65);
+      expect(fill.stops[1].opacity).toBe(0.35);
+      // fillOpacity should be 1 so gradient stop-opacity controls the fade
+      expect(mark.fillOpacity).toBe(1);
+    }
+  });
+
+  it('stacked: markDef.fill string still overrides per-layer gradient', () => {
+    const spec = makeMultiSeriesSpec();
+    spec.encoding.y!.stack = 'zero';
+    spec.markDef = { type: 'area', fill: '#ff00ff' };
+    const scales = computeScales(spec, chartArea, spec.data);
+    const marks = computeAreaMarks(spec, scales, chartArea);
+
+    for (const mark of marks) {
+      expect(mark.fill).toBe('#ff00ff');
+      // Falls back to the historical 0.7 fillOpacity when user supplies flat color
+      expect(mark.fillOpacity).toBe(0.7);
+    }
+  });
+
   describe('x-axis sorting', () => {
     it('sorts unsorted temporal data for single area', () => {
       const spec: NormalizedChartSpec = {
@@ -536,6 +660,30 @@ describe('computeAreaMarks', () => {
     });
 
     it('sorts unsorted temporal data for stacked area', () => {
+      const base = makeMultiSeriesSpec();
+      base.encoding.y!.stack = 'zero';
+      const spec: NormalizedChartSpec = {
+        ...base,
+        data: [
+          { date: '2022-01-01', value: 30, country: 'US' },
+          { date: '2020-01-01', value: 10, country: 'US' },
+          { date: '2021-01-01', value: 40, country: 'US' },
+          { date: '2022-01-01', value: 45, country: 'UK' },
+          { date: '2020-01-01', value: 15, country: 'UK' },
+          { date: '2021-01-01', value: 35, country: 'UK' },
+        ],
+      };
+      const scales = computeScales(spec, chartArea, spec.data);
+      const marks = computeAreaMarks(spec, scales, chartArea);
+
+      for (const mark of marks) {
+        for (let i = 1; i < mark.topPoints.length; i++) {
+          expect(mark.topPoints[i].x).toBeGreaterThan(mark.topPoints[i - 1].x);
+        }
+      }
+    });
+
+    it('sorts unsorted temporal data for overlap (multi-series default)', () => {
       const spec: NormalizedChartSpec = {
         ...makeMultiSeriesSpec(),
         data: [
@@ -550,6 +698,7 @@ describe('computeAreaMarks', () => {
       const scales = computeScales(spec, chartArea, spec.data);
       const marks = computeAreaMarks(spec, scales, chartArea);
 
+      expect(marks).toHaveLength(2);
       for (const mark of marks) {
         for (let i = 1; i < mark.topPoints.length; i++) {
           expect(mark.topPoints[i].x).toBeGreaterThan(mark.topPoints[i - 1].x);
@@ -590,7 +739,7 @@ describe('computeAreaMarks', () => {
         ],
         encoding: {
           x: { field: 'date', type: 'temporal' },
-          y: { field: 'value', type: 'quantitative' },
+          y: { field: 'value', type: 'quantitative', stack: 'zero' },
           color: { field: 'region', type: 'nominal' },
         },
         chrome: {},
@@ -635,6 +784,7 @@ describe('computeAreaMarks', () => {
 
   it('stacked areas: each layer has different baselines', () => {
     const spec = makeMultiSeriesSpec();
+    spec.encoding.y!.stack = 'zero';
     const scales = computeScales(spec, chartArea, spec.data);
     const marks = computeAreaMarks(spec, scales, chartArea);
 
@@ -664,7 +814,7 @@ describe('computeAreaMarks', () => {
       ],
       encoding: {
         x: { field: 'date', type: 'temporal' },
-        y: { field: 'value', type: 'quantitative' },
+        y: { field: 'value', type: 'quantitative', stack: 'zero' },
         color: { field: 'group', type: 'nominal' },
       },
       chrome: {},