@opendata-ai/openchart-engine 6.28.6 → 7.0.0

package/src/charts/line/area.ts

@@ -2,8 +2,13 @@
  * Area chart mark computation.
  *
  * Uses D3 area() generator to produce AreaMark[] with top/bottom
- * boundary points and SVG path strings. Supports single areas and
- * stacked areas via d3-shape stack layout.
+ * 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'`.
+ * - Single series always renders one gradient-filled area.
  */
 
 import type { AreaMark, DataRow, Encoding, MarkAria, Rect } from '@opendata-ai/openchart-core';
@@ -30,10 +35,76 @@ import { resolveCurve } from './curves';
 
 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.
+ */
+function isStacked(stackProp: unknown): boolean {
+  if (stackProp === undefined || stackProp === null || stackProp === false) {
+    return false;
+  }
+  return (
+    stackProp === true ||
+    stackProp === 'zero' ||
+    stackProp === 'normalize' ||
+    stackProp === 'center'
+  );
+}
+
+// Gradient stops calibrated by series count. Solo areas can carry richer fills
+// because there's no overlap to manage; multi-series overlap needs lighter
+// stops so layered bands stay legible.
+const SOLO_GRADIENT_STOPS = [
+  { offset: 0, opacity: 0.42 },
+  { offset: 0.6, opacity: 0.1 },
+  { offset: 1, opacity: 0 },
+];
+
+const OVERLAP_GRADIENT_STOPS = [
+  { offset: 0, opacity: 0.22 },
+  { offset: 0.7, opacity: 0.04 },
+  { offset: 1, opacity: 0 },
+];
+
+// Stacked layers sit on top of each other and need higher opacity so each
+// band reads as a distinct quantity. A gentle top-to-bottom gradient adds
+// depth without losing the categorical color identity.
+const STACKED_GRADIENT_STOPS = [
+  { offset: 0, opacity: 0.65 },
+  { offset: 1, opacity: 0.35 },
+];
+
+function buildGradientFill(
+  colorStr: string,
+  stops: ReadonlyArray<{ offset: number; opacity: number }>,
+): import('@opendata-ai/openchart-core').GradientDef {
+  return {
+    gradient: 'linear',
+    x1: 0,
+    y1: 0,
+    x2: 0,
+    y2: 1,
+    stops: stops.map((s) => ({ offset: s.offset, color: colorStr, opacity: s.opacity })),
+  };
+}
+
 // ---------------------------------------------------------------------------
-// Single area (non-stacked)
+// Single / overlap area (non-stacked)
 // ---------------------------------------------------------------------------
 
+/**
+ * Compute area marks for non-stacked rendering.
+ *
+ * - With no `color` field: emits a single area with the solo gradient.
+ * - With a `color` field (overlap mode): emits one area per series, each
+ *   anchored at the y-domain baseline and using the lighter overlap gradient.
+ */
 function computeSingleArea(
   spec: NormalizedChartSpec,
   scales: ResolvedScales,
@@ -69,6 +140,9 @@ function computeSingleArea(
     }
   }
 
+  const isMultiSeries = colorField !== undefined && groups.size > 1;
+  const defaultGradientStops = isMultiSeries ? OVERLAP_GRADIENT_STOPS : SOLO_GRADIENT_STOPS;
+
   const marks: AreaMark[] = [];
 
   for (const [seriesKey, rows] of groups) {
@@ -137,7 +211,8 @@ function computeSingleArea(
 
     // Allow markDef.fill to override color with a gradient.
     // When a gradient is provided, set fillOpacity=1 so gradient stop-opacity controls the fade.
-    // When no fill is provided, auto-generate a top-to-bottom fade gradient.
+    // When no fill is provided, auto-generate a top-to-bottom fade gradient
+    // tuned to series count (lighter for overlap).
     const markFill = spec.markDef.fill;
     let fillValue: string | import('@opendata-ai/openchart-core').GradientDef;
     let fillOpacity: number;
@@ -149,17 +224,7 @@ function computeSingleArea(
         : (spec.markDef.opacity ?? (y2Channel ? 0.25 : DEFAULT_FILL_OPACITY));
     } else {
       const colorStr = getRepresentativeColor(color);
-      fillValue = {
-        gradient: 'linear',
-        x1: 0,
-        y1: 0,
-        x2: 0,
-        y2: 1,
-        stops: [
-          { offset: 0, color: colorStr, opacity: 0.12 },
-          { offset: 1, color: colorStr, opacity: 0 },
-        ],
-      };
+      fillValue = buildGradientFill(colorStr, defaultGradientStops);
       fillOpacity = 1;
     }
 
@@ -171,8 +236,9 @@ function computeSingleArea(
       topPath: topPathStr,
       fill: fillValue,
       fillOpacity: fillOpacity,
-      stroke: getRepresentativeColor(isGradientDef(fillValue) ? color : fillValue),
-      strokeWidth: spec.markDef.strokeWidth ?? (spec.display === 'sparkline' ? 1.25 : 1.5),
+      stroke:
+        spec.markDef.stroke ?? getRepresentativeColor(isGradientDef(fillValue) ? color : fillValue),
+      strokeWidth: spec.markDef.strokeWidth ?? 1.5,
       seriesKey: seriesKey === '__default__' ? undefined : seriesKey,
       data: validPoints.map((p) => p.row),
       dataPoints: validPoints.map((p) => ({ x: p.x, y: p.yTop, datum: p.row })),
@@ -312,14 +378,29 @@ function computeStackedArea(
       label: `${seriesKey}: stacked area with ${validPoints.length} data points`,
     };
 
+    // Per-layer top-to-bottom gradient. User-supplied markDef.fill (string or
+    // gradient) overrides the auto gradient just like in single-area mode.
+    const markFill = spec.markDef.fill;
+    let fillValue: string | import('@opendata-ai/openchart-core').GradientDef;
+    let fillOpacity: number;
+
+    if (markFill != null) {
+      fillValue = markFill;
+      fillOpacity = isGradientDef(markFill) ? 1 : (spec.markDef.opacity ?? 0.7);
+    } else {
+      const colorStr = getRepresentativeColor(color);
+      fillValue = buildGradientFill(colorStr, STACKED_GRADIENT_STOPS);
+      fillOpacity = 1;
+    }
+
     marks.push({
       type: 'area',
       topPoints,
       bottomPoints,
       path: pathStr,
       topPath: topPathStr,
-      fill: color,
-      fillOpacity: 0.7, // Higher opacity for stacked so layers are visible
+      fill: fillValue,
+      fillOpacity,
       stroke: getRepresentativeColor(color),
       strokeWidth: 1,
       seriesKey,
@@ -348,8 +429,15 @@ function computeStackedArea(
 /**
  * Compute area marks from a normalized chart spec.
  *
- * For multi-series with color encoding, produces stacked areas.
- * For single series, produces a simple area fill from the line to baseline (y=0).
+ * Behavior depends on `encoding.y.stack` (Vega-Lite aligned):
+ * - `undefined | null | false` -> overlap (default for multi-series)
+ * - `true | 'zero' | 'normalize' | 'center'` -> stacked
+ *
+ * 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,
@@ -357,9 +445,9 @@ export function computeAreaMarks(
   chartArea: Rect,
 ): AreaMark[] {
   const encoding = spec.encoding as Encoding;
-  const hasColor = !!encoding.color;
+  const yChannel = encoding.y;
 
-  if (hasColor) {
+  if (yChannel && isStacked(yChannel.stack)) {
     return computeStackedArea(spec, scales, chartArea);
   }
 

package/src/charts/line/compute.ts

@@ -29,13 +29,10 @@ import { resolveCurve } from './curves';
 // Constants
 // ---------------------------------------------------------------------------
 
-/** Default stroke width for line marks. */
+/** Default stroke width for line marks. Sparklines use the same width so the
+ *  visual weight matches the rest of the chart family. */
 const DEFAULT_STROKE_WIDTH = 1.5;
 
-/** Sparkline mode uses a thinner stroke since the chart area is tiny and a
- *  2.5px line reads as clunky. 1.25px keeps the trend legible without dominating. */
-const SPARKLINE_STROKE_WIDTH = 1.25;
-
 /** Default radius for point marks (hover targets). */
 const DEFAULT_POINT_RADIUS = 3;
 
@@ -77,7 +74,10 @@ export function computeLineMarks(
     const color: string | GradientDef = isSequentialColor
       ? getSequentialColor(scales, _getMidValue(rows, sequentialColorField!))
       : getColor(scales, seriesKey);
-    const strokeColor = getRepresentativeColor(color);
+    // markDef.stroke wins over the scale-derived color when set explicitly.
+    // Sparkline mode injects this via applySparklineDefaults to carry the
+    // trend color; users can also set it directly to override the palette.
+    const strokeColor = spec.markDef.stroke ?? getRepresentativeColor(color);
 
     // Sort rows by x-axis field so lines draw left-to-right.
     // For nominal/ordinal axes, preserve data order since there's no
@@ -178,10 +178,7 @@ export function computeLineMarks(
       points: allPoints,
       path: combinedPath,
       stroke: strokeColor,
-      strokeWidth:
-        styleOverride?.strokeWidth ??
-        spec.markDef.strokeWidth ??
-        (spec.display === 'sparkline' ? SPARKLINE_STROKE_WIDTH : DEFAULT_STROKE_WIDTH),
+      strokeWidth: styleOverride?.strokeWidth ?? spec.markDef.strokeWidth ?? DEFAULT_STROKE_WIDTH,
       strokeDasharray,
       opacity: styleOverride?.opacity,
       seriesKey: seriesStyleKey,
@@ -195,10 +192,12 @@ export function computeLineMarks(
     // Emit PointMark objects when markDef.point is truthy, or when sequential
     // color is active (points carry the gradient since SVG paths are single-color).
     const markPoint = spec.markDef.point;
+    const isSingleEndpoint = markPoint === 'last' || markPoint === 'first';
     const showPoints =
       markPoint === true ||
       markPoint === 'transparent' ||
       markPoint === 'endpoints' ||
+      isSingleEndpoint ||
       isSequentialColor;
 
     if (showPoints) {
@@ -211,6 +210,14 @@ export function computeLineMarks(
       for (let i = 0; i < pointsWithData.length; i++) {
         const p = pointsWithData[i];
         const isEndpoint = i === 0 || i === lastIdx;
+        const isLast = i === lastIdx;
+        const isFirst = i === 0;
+        // Single-endpoint mode ('last' / 'first'): emit only the chosen point.
+        // Skip the others entirely instead of emitting invisible placeholders.
+        if (isSingleEndpoint) {
+          if (markPoint === 'last' && !isLast) continue;
+          if (markPoint === 'first' && !isFirst) continue;
+        }
         const visible = seriesShowPoints && !isTransparent && (!isEndpoints || isEndpoint);
         // Sequential color: each point gets colored by its data value
         let pointColor = color;
@@ -220,6 +227,29 @@ export function computeLineMarks(
         }
         const hollow = isEndpoints && visible;
         const pointColorStr = getRepresentativeColor(pointColor);
+        // 'last' / 'first' render as a tight filled terminator dot in the line
+        // color — no white halo, no hollow ring. Marked decorative because the
+        // data point already exists on the line and gets described by the a11y
+        // data table; the dot is purely visual.
+        if (isSingleEndpoint) {
+          marks.push({
+            type: 'point',
+            cx: p.x,
+            cy: p.y,
+            // 3.5 reads as a deliberate terminator against the 2px sparkline
+            // line — smaller dots blur into the stroke at typical card sizes.
+            r: 3.5,
+            fill: strokeColor,
+            stroke: 'transparent',
+            strokeWidth: 0,
+            fillOpacity: 1,
+            data: p.row,
+            // No label: decorative marks render with aria-hidden="true" and
+            // don't participate in the accessible data table.
+            aria: { decorative: true },
+          });
+          continue;
+        }
         const pointMark: PointMark = {
           type: 'point',
           cx: p.x,

package/src/charts/line/index.ts

@@ -2,6 +2,12 @@
  * Line & area chart module.
  *
  * Exports line and area chart renderers and computation functions.
+ *
+ * Area chart multi-series defaults (v6):
+ * - Default with `color` encoding is **overlap** -- one translucent gradient
+ *   band per series, all anchored at the y-domain baseline.
+ * - Stacked rendering is opt-in: set `encoding.y.stack` to `true`, `'zero'`,
+ *   `'normalize'`, or `'center'`.
  */
 
 import type { AreaMark, LineMark, Mark } from '@opendata-ai/openchart-core';
@@ -27,8 +33,16 @@ export const lineRenderer: ChartRenderer = (spec, scales, chartArea, strategy, _
   // Extract just the line marks for label computation
   const lineMarks = marks.filter((m): m is LineMark => m.type === 'line');
 
-  // Compute and attach labels to line marks by seriesKey lookup
-  const labelMap = computeLineLabels(lineMarks, strategy, spec.labels.density, spec.labels.offsets);
+  // Compute and attach labels to line marks by seriesKey lookup. Passing the
+  // spec engages the shared suppression truth table so end-of-line labels
+  // hide when the legend or endpoint column is showing.
+  const labelMap = computeLineLabels(
+    lineMarks,
+    strategy,
+    spec.labels.density,
+    spec.labels.offsets,
+    spec,
+  );
   for (const mark of marks) {
     if (mark.type === 'line' && mark.seriesKey) {
       const label = labelMap.get(mark.seriesKey);
@@ -48,9 +62,14 @@ export const lineRenderer: ChartRenderer = (spec, scales, chartArea, strategy, _
 /**
  * Area chart renderer.
  *
- * Computes area fill marks (stacked if multi-series).
+ * Computes area fill marks (stacked or overlapping per `encoding.y.stack`).
  * Also computes line marks for the top boundary and point marks
  * for hover targets, layered on top of the areas.
+ *
+ * Lines are derived from area top boundaries whenever there's a color
+ * encoding -- this keeps each line glued to its band's top edge regardless
+ * of whether the layout is stacked (cumulative tops) or overlap (per-series
+ * raw values).
  */
 export const areaRenderer: ChartRenderer = (spec, scales, chartArea, strategy, _theme) => {
   const areas = computeAreaMarks(spec, scales, chartArea);
@@ -58,8 +77,9 @@ export const areaRenderer: ChartRenderer = (spec, scales, chartArea, strategy, _
   const encoding = spec.encoding;
   const hasColor = !!(encoding.color && 'field' in encoding.color);
 
-  // For stacked areas, derive line marks from the area top paths so lines
-  // align with stacked positions. For non-stacked, compute lines normally.
+  // With a color encoding (stacked or overlap), derive line marks from the
+  // area tops so each line traces the upper edge of its band. For single
+  // series, compute lines normally so we get the regular line + point marks.
   const lines = hasColor
     ? linesFromAreas(areas)
     : computeLineMarks(spec, scales, chartArea, strategy);
@@ -73,8 +93,15 @@ export const areaRenderer: ChartRenderer = (spec, scales, chartArea, strategy, _
 // ---------------------------------------------------------------------------
 
 /**
- * Derive LineMark[] from stacked AreaMark[] using each area's top boundary.
- * This ensures lines sit on top of their corresponding stacked area bands.
+ * Derive LineMark[] from AreaMark[] using each area's top boundary.
+ *
+ * Works for both stacked and overlap layouts:
+ * - Stacked: `topPoints` is the cumulative top edge of the layer, so the line
+ *   sits on top of its band rather than the raw series value.
+ * - Overlap: `topPoints` is the series' own y value (areas all share the same
+ *   baseline), so the line traces the actual data.
+ *
+ * No z-order assumption -- each area independently provides its own top.
  */
 function linesFromAreas(areas: AreaMark[]): LineMark[] {
   return areas.map((a) => ({

package/src/charts/line/labels.ts

@@ -25,6 +25,9 @@ import {
   resolveCollisions,
 } from '@opendata-ai/openchart-core';
 
+import type { NormalizedChartSpec } from '../../compiler/types';
+import { countColorSeries, resolveSuppression } from '../../legend/suppression';
+
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
@@ -56,6 +59,11 @@ const LABEL_OFFSET_X = 6;
  * @param marks - Line marks (only processes marks with type === 'line').
  * @param strategy - Layout strategy from the responsive breakpoint.
  * @param density - Label density mode from spec.labels.density.
+ * @param labelOffsets - Per-series user offsets applied after collision resolution.
+ * @param spec - Optional normalized spec. When provided, the shared suppression
+ *   truth table gates rendering: end-of-line labels are the last-resort series
+ *   identifier and only render when both the traditional legend and endpoint
+ *   labels column are off.
  * @returns Map of seriesKey -> ResolvedLabel after collision detection.
  */
 export function computeLineLabels(
@@ -63,6 +71,7 @@ export function computeLineLabels(
   strategy: LayoutStrategy,
   density: LabelDensity = 'auto',
   labelOffsets?: Record<string, { dx?: number; dy?: number }>,
+  spec?: NormalizedChartSpec,
 ): Map<string, ResolvedLabel> {
   const result = new Map<string, ResolvedLabel>();
 
@@ -74,6 +83,26 @@ export function computeLineLabels(
     return result;
   }
 
+  // Suppression truth table: when the spec is available, defer to the shared
+  // helper. End-of-line labels render only when both the legend and endpoint
+  // column are off — they're the last-resort series identifier.
+  if (spec) {
+    // The 'none' branches above already returned, so by here labelMode and
+    // density are not 'none'. Pass false explicitly to keep the helper pure.
+    const suppression = resolveSuppression(spec, {
+      seriesCount: countColorSeries(spec),
+      labelsHiddenByStrategy: false,
+      labelsDensityNone: false,
+    });
+    if (!suppression.showEndOfLineLabels) {
+      // Single-series charts have no series-name end-of-line label to hide
+      // (computeLineLabels returns nothing when seriesKey is empty). For
+      // multi-series, the suppression result tells us to skip explicitly.
+      const isMultiSeries = !!spec.encoding.color && countColorSeries(spec) >= 2;
+      if (isMultiSeries) return result;
+    }
+  }
+
   const candidates: LabelCandidate[] = [];
   const seriesOrder: string[] = [];
 

package/src/charts/pie/labels.ts

@@ -66,6 +66,7 @@ export function computePieLabels(
     // Format is "Category: value (percent%)". Split on the first colon
     // to handle category names that might contain colons.
     const ariaLabel = mark.aria.label;
+    if (!ariaLabel) continue;
     const firstColon = ariaLabel.indexOf(':');
     const labelText = firstColon >= 0 ? ariaLabel.slice(0, firstColon).trim() : '';
     if (!labelText) continue;