@opendata-ai/openchart-engine 7.10.0 → 8.0.0-rc.1

package/src/charts/column/labels.ts

@@ -2,7 +2,10 @@
  * Column chart label computation.
  *
  * Produces value labels positioned above each column (for positive values)
- * or below (for negative values).
+ * or below (for negative values). Stacked segments are the exception: the
+ * space above a segment's top edge belongs to the next segment up, not to the
+ * background, so a stacked label is centered *inside* its own segment and
+ * takes a contrasting fill (mirrors computeBarLabels).
  *
  * Respects the spec's label density setting:
  * - 'all': consider every column's label (no density pre-filter), but still
@@ -16,13 +19,14 @@
 import type {
   LabelCandidate,
   LabelDensity,
+  NumberFormatter,
   RectMark,
   ResolvedLabel,
 } from '@opendata-ai/openchart-core';
 import {
-  buildD3Formatter,
   estimateTextWidth,
   getRepresentativeColor,
+  pickLabelColor,
   resolveCollisions,
   textAscent,
 } from '@opendata-ai/openchart-core';
@@ -36,6 +40,8 @@ import { formatLabelValue } from '../_shared/format-label-value';
 const LABEL_FONT_SIZE = 10;
 const LABEL_FONT_WEIGHT = 600;
 const LABEL_OFFSET_Y = 8;
+/** Vertical padding inside a stacked segment, above and below the label. */
+const LABEL_PADDING_Y = 2;
 
 // ---------------------------------------------------------------------------
 // Public API
@@ -50,19 +56,23 @@ export function computeColumnLabels(
   marks: RectMark[],
   _chartArea: { x: number; y: number; width: number; height: number },
   density: LabelDensity = 'auto',
-  labelFormat?: string,
+  labelFormatter?: NumberFormatter | null,
   labelPrefix?: string,
   valueField?: string,
   labelColor?: string,
+  darkMode = false,
   fontSize?: number,
   labelSuffix?: string,
 ): ResolvedLabel[] {
   const FONT_SIZE = fontSize ?? LABEL_FONT_SIZE;
   const targetMarks = filterByDensity(marks, density);
 
-  const formatter = buildD3Formatter(labelFormat);
+  const formatter = labelFormatter ?? null;
 
   const candidates: LabelCandidate[] = [];
+  // Track whether each candidate fits inside its stacked segment. Non-stacked
+  // columns label into open space above the bar, so they always fit.
+  const fitsInSegment: boolean[] = [];
 
   for (const mark of targetMarks) {
     // Get the original numeric value from the data row when possible,
@@ -98,16 +108,38 @@ export function computeColumnLabels(
     const textWidth = estimateTextWidth(valuePart, FONT_SIZE, LABEL_FONT_WEIGHT);
     const textHeight = FONT_SIZE * 1.2;
 
+    // A stacked segment has another segment sitting directly on top of it, so
+    // the "float above the top edge" placement used for plain columns would
+    // drop the label into its neighbour — and tint it with this segment's
+    // color, guaranteeing colored-text-on-colored-fill. Center it inside its
+    // own segment instead and pick a fill that contrasts with that segment.
+    const isStacked = mark.stackGroup !== undefined;
+
     // anchorY is the TOP of the label bounding box so the collision system's
     // AABB check (rect = { y: anchorY, height: textHeight }) is geometrically
     // correct. Collision math stays in top-coordinate space; the ascent shift
     // to the alphabetic baseline is applied only at emission (see below).
+    //   Stacked:      top = segment center - textHeight / 2, text sits within
     //   Positive bar: top = barTop - LABEL_OFFSET_Y - textHeight, text floats above
     //   Negative bar: top = barBottom + LABEL_OFFSET_Y, text hangs below
     const anchorX = mark.x + mark.width / 2;
-    const anchorY = isNegative
-      ? mark.y + mark.height + LABEL_OFFSET_Y
-      : mark.y - LABEL_OFFSET_Y - textHeight;
+    let anchorY: number;
+    let fill: string;
+
+    if (isStacked) {
+      anchorY = mark.y + mark.height / 2 - textHeight / 2;
+      fill = labelColor ?? pickLabelColor(getRepresentativeColor(mark.fill), darkMode);
+    } else {
+      anchorY = isNegative
+        ? mark.y + mark.height + LABEL_OFFSET_Y
+        : mark.y - LABEL_OFFSET_Y - textHeight;
+      fill = labelColor ?? getRepresentativeColor(mark.fill);
+    }
+
+    // A label only belongs inside a stacked segment if the segment is tall
+    // enough to hold it; short segments (Nuclear at ~4%) would otherwise
+    // overflow into their neighbours.
+    fitsInSegment.push(!(isStacked && textHeight > mark.height - 2 * LABEL_PADDING_Y));
 
     candidates.push({
       text: valuePart,
@@ -120,7 +152,7 @@ export function computeColumnLabels(
         fontFamily: 'system-ui, -apple-system, sans-serif',
         fontSize: FONT_SIZE,
         fontWeight: LABEL_FONT_WEIGHT,
-        fill: labelColor ?? getRepresentativeColor(mark.fill),
+        fill,
         lineHeight: 1.2,
         textAnchor: 'middle',
         fontVariant: 'tabular-nums',
@@ -136,20 +168,62 @@ export function computeColumnLabels(
   // hanging from different font metrics than Blink, clipping labels on iOS).
   const ascent = textAscent(FONT_SIZE);
 
-  // Every density that reaches here ('all' and 'auto') runs collision
+  // Every density that reaches here ('all' and 'auto') pre-hides candidates
+  // whose stacked segment is too short to hold them, then runs collision
   // resolution. 'all' just skips the density pre-filter above so every mark is
   // a candidate; colliding losers are still hidden by resolveCollisions rather
   // than stacked on top of each other.
-  return resolveCollisions(candidates).map((label) => ({
-    ...label,
-    y: label.y + ascent,
-    // The connector originates at the label; shift its start to the baseline
-    // too so the leader stays glued to the shifted text.
-    connector: label.connector
-      ? {
-          ...label.connector,
-          from: { ...label.connector.from, y: label.connector.from.y + ascent },
-        }
-      : undefined,
-  }));
+  const fittingCandidates: LabelCandidate[] = [];
+  const unfittingIndices = new Set<number>();
+  for (let i = 0; i < candidates.length; i++) {
+    if (fitsInSegment[i] === false) {
+      unfittingIndices.add(i);
+    } else {
+      // Carry the original candidate index so we can zip the resolved output
+      // back to it regardless of any reordering resolveCollisions performs.
+      fittingCandidates.push({ ...candidates[i], index: i });
+    }
+  }
+
+  // resolveCollisions may reorder its output (it sorts by priority), so key the
+  // result by the source index we carried rather than by position.
+  const resolvedByOrig = new Map<number, ResolvedLabel>();
+  for (const r of resolveCollisions(fittingCandidates)) {
+    if (r.index !== undefined) resolvedByOrig.set(r.index, r);
+  }
+
+  // Re-emit hidden labels rather than dropping them: the renderer zips
+  // marks[i].label = labels[i], so the output must stay index-aligned.
+  const results: ResolvedLabel[] = [];
+  for (let i = 0; i < candidates.length; i++) {
+    if (unfittingIndices.has(i)) {
+      results.push({
+        text: candidates[i].text,
+        x: candidates[i].anchorX,
+        y: candidates[i].anchorY + ascent,
+        style: candidates[i].style,
+        visible: false,
+      });
+      continue;
+    }
+
+    const r = resolvedByOrig.get(i);
+    if (!r) continue;
+    // Drop the internal zip index so it doesn't leak into the label output.
+    const { index: _index, ...rest } = r;
+    results.push({
+      ...rest,
+      y: r.y + ascent,
+      // The connector originates at the label; shift its start to the baseline
+      // too so the leader stays glued to the shifted text.
+      connector: r.connector
+        ? {
+            ...r.connector,
+            from: { ...r.connector.from, y: r.connector.from.y + ascent },
+          }
+        : undefined,
+    });
+  }
+
+  return results;
 }

package/src/charts/dot/index.ts

@@ -5,6 +5,7 @@
  */
 
 import type { Mark, PointMark } from '@opendata-ai/openchart-core';
+import { resolveFieldFormatter } from '../../format/field-format';
 import type { ChartRenderer } from '../registry';
 import { computeDotMarks } from './compute';
 import { computeDotLabels } from './labels';
@@ -28,12 +29,18 @@ export const dotRenderer: ChartRenderer = (spec, scales, chartArea, strategy, _t
   // Compute and attach labels to point marks (respects spec.labels.density)
   const valueField =
     spec.encoding?.x && 'field' in spec.encoding.x ? spec.encoding.x.field : undefined;
+  const labelFormatter = resolveFieldFormatter({
+    surfaceFormat: spec.labels.format,
+    channelFormat:
+      spec.encoding?.x && 'format' in spec.encoding.x ? spec.encoding.x.format : undefined,
+    values: valueField ? spec.data.map((r) => r[valueField]) : [],
+  });
   const labels = computeDotLabels(
     pointMarks,
     chartArea,
     spec.labels.density,
     spec.labels.prefix,
-    spec.labels.format,
+    labelFormatter,
     valueField,
   );
   let labelIdx = 0;

package/src/charts/dot/labels.ts

@@ -13,12 +13,12 @@
 import type {
   LabelCandidate,
   LabelDensity,
+  NumberFormatter,
   PointMark,
   Rect,
   ResolvedLabel,
 } from '@opendata-ai/openchart-core';
 import {
-  buildD3Formatter,
   estimateTextWidth,
   getRepresentativeColor,
   resolveCollisions,
@@ -48,12 +48,12 @@ export function computeDotLabels(
   _chartArea: Rect,
   density: LabelDensity = 'auto',
   labelPrefix?: string,
-  labelFormat?: string,
+  labelFormatter?: NumberFormatter | null,
   valueField?: string,
 ): ResolvedLabel[] {
   const targetMarks = filterByDensity(marks, density);
 
-  const formatter = buildD3Formatter(labelFormat);
+  const formatter = labelFormatter ?? null;
   const candidates: LabelCandidate[] = [];
 
   for (const mark of targetMarks) {

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

@@ -517,8 +517,8 @@ 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.
+  it('stacked (default): produces multiple AreaMarks for multi-series without an explicit stack', () => {
+    // v8 VL-aligned default: multi-series with color stacks unless `stack: null | false`.
     const spec = makeMultiSeriesSpec();
     const scales = computeScales(spec, chartArea, spec.data);
     const marks = computeAreaMarks(spec, scales, chartArea);
@@ -527,10 +527,15 @@ describe('computeAreaMarks', () => {
     const seriesKeys = marks.map((m) => m.seriesKey).filter(Boolean);
     expect(seriesKeys).toContain('US');
     expect(seriesKeys).toContain('UK');
+    // 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('overlap: every series shares the same baseline (no stacking offset)', () => {
+  it('overlap (stack: null): every series shares the same baseline (no stacking offset)', () => {
     const spec = makeMultiSeriesSpec();
+    spec.encoding.y!.stack = null;
     const scales = computeScales(spec, chartArea, spec.data);
     const marks = computeAreaMarks(spec, scales, chartArea);
 
@@ -544,8 +549,9 @@ describe('computeAreaMarks', () => {
     expect(baselines.size).toBe(1);
   });
 
-  it('overlap: each series uses a translucent gradient fill', () => {
+  it('overlap (stack: null): each series uses a translucent gradient fill', () => {
     const spec = makeMultiSeriesSpec();
+    spec.encoding.y!.stack = null;
     const scales = computeScales(spec, chartArea, spec.data);
     const marks = computeAreaMarks(spec, scales, chartArea);
 
@@ -560,19 +566,7 @@ describe('computeAreaMarks', () => {
     }
   });
 
-  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)', () => {
+  it('stack: false opts into overlap rendering, same as stack: null', () => {
     const spec = makeMultiSeriesSpec();
     spec.encoding.y!.stack = false;
     const scales = computeScales(spec, chartArea, spec.data);
@@ -702,9 +696,11 @@ describe('computeAreaMarks', () => {
       }
     });
 
-    it('sorts unsorted temporal data for overlap (multi-series default)', () => {
+    it('sorts unsorted temporal data for overlap (stack: null)', () => {
+      const base = makeMultiSeriesSpec();
+      base.encoding.y!.stack = null;
       const spec: NormalizedChartSpec = {
-        ...makeMultiSeriesSpec(),
+        ...base,
         data: [
           { date: '2022-01-01', value: 30, country: 'US' },
           { date: '2020-01-01', value: 10, country: 'US' },

package/src/charts/line/area.ts

@@ -4,10 +4,9 @@
  * Uses D3 area() generator to produce AreaMark[] with top/bottom
  * boundary points and SVG path strings.
  *
- * Multi-series behavior (v6 redesign):
- * - Default for multi-series with `color` is **overlap** (one translucent
- *   gradient band per series, layered with low opacity).
- * - Stacked rendering is opt-in via `encoding.y.stack: 'zero' | true | 'normalize' | 'center'`.
+ * Multi-series behavior (v8: VL-aligned defaults):
+ * - Default for multi-series with `color` is **stacked** from a zero baseline.
+ * - Overlap rendering is opt-out via `encoding.y.stack: null | false`.
  * - Single series always renders one gradient-filled area.
  */
 
@@ -40,22 +39,11 @@ const DEFAULT_FILL_OPACITY = 0.15;
  * Resolve `encoding.y.stack` to a boolean: should we stack this area chart?
  *
  * Vega-Lite-aligned semantics:
- * - undefined | null | false  -> overlap (NEW DEFAULT for area)
- * - true | 'zero' | 'normalize' | 'center' -> stacked
- *
- * This is a v6 breaking change. Previously, multi-series with `color`
- * implicitly stacked. Now overlap is the default; stacking is opt-in.
+ * - undefined | true | 'zero' | 'normalize' | 'center' -> stacked (default)
+ * - null | false -> overlap (opt-out)
  */
 function isStacked(stackProp: unknown): boolean {
-  if (stackProp === undefined || stackProp === null || stackProp === false) {
-    return false;
-  }
-  return (
-    stackProp === true ||
-    stackProp === 'zero' ||
-    stackProp === 'normalize' ||
-    stackProp === 'center'
-  );
+  return stackProp !== null && stackProp !== false;
 }
 
 // Gradient stops calibrated by series count. Solo areas can carry richer fills
@@ -453,14 +441,11 @@ function computeStackedArea(
  * Compute area marks from a normalized chart spec.
  *
  * Behavior depends on `encoding.y.stack` (Vega-Lite aligned):
- * - `undefined | null | false` -> overlap (default for multi-series)
- * - `true | 'zero' | 'normalize' | 'center'` -> stacked
+ * - `undefined | true | 'zero' | 'normalize' | 'center'` -> stacked (default for multi-series)
+ * - `null | false` -> overlap
  *
  * Single-series specs always render one gradient-filled area; the `stack`
  * branch only matters when a `color` encoding is present.
- *
- * BREAKING CHANGE (v6): multi-series no longer auto-stacks. Pass
- * `encoding.y.stack: 'zero'` (or `true`) to opt back into the old behavior.
  */
 export function computeAreaMarks(
   spec: NormalizedChartSpec,

package/src/charts/line/compute.ts

@@ -37,6 +37,11 @@ const DEFAULT_STROKE_WIDTH = 1.5;
 /** Default radius for point marks (hover targets). */
 const DEFAULT_POINT_RADIUS = 3;
 
+/** Dash patterns cycled through by the strokeDash encoding, assigned in the
+ *  ordinal (first-seen data) order of the field values. The first value
+ *  renders solid so single-value charts keep the default look. */
+const STROKE_DASH_PATTERNS = ['', '6 4', '2 3', '8 4 2 4', '4 4', '1 3'];
+
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
@@ -67,7 +72,23 @@ export function computeLineMarks(
   // Sequential color: single series, per-point coloring. Categorical: group by color field.
   const colorField = isSequentialColor ? undefined : colorEnc?.field;
   const sequentialColorField = isSequentialColor ? colorEnc.field : undefined;
-  const groups = groupByField(spec.data, colorField);
+  // strokeDash encoding: differentiate series by dash pattern (VL aligned).
+  // Without a color channel, the strokeDash field becomes the series grouping
+  // so each dash value renders as its own line. With a color channel, each
+  // series takes the dash of its first row (typically the same field).
+  const dashEnc =
+    encoding.strokeDash && 'field' in encoding.strokeDash ? encoding.strokeDash : undefined;
+  const dashField = dashEnc?.field;
+  const dashIndexByValue = new Map<string, number>();
+  if (dashField) {
+    for (const row of spec.data) {
+      const value = row[dashField];
+      if (value == null) continue;
+      const key = String(value);
+      if (!dashIndexByValue.has(key)) dashIndexByValue.set(key, dashIndexByValue.size);
+    }
+  }
+  const groups = groupByField(spec.data, colorField ?? dashField);
   const mutedMarks: (LineMark | PointMark)[] = [];
   const highlightedMarks: (LineMark | PointMark)[] = [];
   const highlight = spec.highlight ?? [];
@@ -176,10 +197,19 @@ export function computeLineMarks(
       resolvedStrokeWidth = Math.max(1, resolvedStrokeWidth * 0.75);
     }
 
-    // Map lineStyle to SVG strokeDasharray
+    // Map lineStyle to SVG strokeDasharray. Explicit seriesStyles win over
+    // the strokeDash encoding.
     let strokeDasharray: string | undefined;
     if (styleOverride?.lineStyle === 'dashed') strokeDasharray = '6 4';
     else if (styleOverride?.lineStyle === 'dotted') strokeDasharray = '2 3';
+    else if (dashField) {
+      const dashValue = rows[0]?.[dashField];
+      if (dashValue != null) {
+        const idx = dashIndexByValue.get(String(dashValue)) ?? 0;
+        const pattern = STROKE_DASH_PATTERNS[idx % STROKE_DASH_PATTERNS.length];
+        if (pattern) strokeDasharray = pattern;
+      }
+    }
 
     // Create the LineMark with the combined path points.
     // The points array includes all valid points across all segments.