@opendata-ai/openchart-engine 1.2.0

package/src/charts/line/area.ts

@@ -0,0 +1,288 @@
+/**
+ * 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.
+ */
+
+import type { AreaMark, DataRow, Encoding, MarkAria, Rect } from '@opendata-ai/openchart-core';
+import type { ScaleLinear } from 'd3-scale';
+import { area, curveMonotoneX, line, stack, stackOffsetNone, stackOrderNone } from 'd3-shape';
+
+import type { NormalizedChartSpec } from '../../compiler/types';
+import type { ResolvedScales } from '../../layout/scales';
+import { getColor, scaleValue } from '../utils';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const DEFAULT_FILL_OPACITY = 0.15;
+
+// ---------------------------------------------------------------------------
+// Single area (non-stacked)
+// ---------------------------------------------------------------------------
+
+function computeSingleArea(
+  spec: NormalizedChartSpec,
+  scales: ResolvedScales,
+  _chartArea: Rect,
+): AreaMark[] {
+  const encoding = spec.encoding as Encoding;
+  const xChannel = encoding.x;
+  const yChannel = encoding.y;
+
+  if (!xChannel || !yChannel || !scales.x || !scales.y) return [];
+
+  const yScale = scales.y.scale as ScaleLinear<number, number>;
+  // Use the domain minimum as the baseline so the area fill doesn't drop
+  // below the visible scale range when zero: false excludes 0 from the domain.
+  const domain = yScale.domain();
+  const baselineY = yScale(Math.min(domain[0], domain[1]));
+
+  // Group by color field
+  const colorField = encoding.color?.field;
+  const groups = new Map<string, DataRow[]>();
+
+  if (!colorField) {
+    groups.set('__default__', spec.data);
+  } else {
+    for (const row of spec.data) {
+      const key = String(row[colorField] ?? '__default__');
+      const existing = groups.get(key);
+      if (existing) {
+        existing.push(row);
+      } else {
+        groups.set(key, [row]);
+      }
+    }
+  }
+
+  const marks: AreaMark[] = [];
+
+  for (const [seriesKey, rows] of groups) {
+    const color = getColor(scales, seriesKey);
+
+    // Compute points, filtering out null values
+    const validPoints: { x: number; yTop: number; yBottom: number; row: DataRow }[] = [];
+
+    for (const row of rows) {
+      const xVal = scaleValue(scales.x.scale, scales.x.type, row[xChannel.field]);
+      const yVal = scaleValue(scales.y.scale, scales.y.type, row[yChannel.field]);
+
+      if (xVal === null || yVal === null) continue;
+
+      validPoints.push({
+        x: xVal,
+        yTop: yVal,
+        yBottom: baselineY,
+        row,
+      });
+    }
+
+    if (validPoints.length === 0) continue;
+
+    // Build the area path
+    const areaGenerator = area<{ x: number; yTop: number; yBottom: number }>()
+      .x((d) => d.x)
+      .y0((d) => d.yBottom)
+      .y1((d) => d.yTop)
+      .curve(curveMonotoneX);
+
+    const pathStr = areaGenerator(validPoints) ?? '';
+
+    // Top-line path for stroking only the data line (not the baseline)
+    const topLineGenerator = line<{ x: number; yTop: number }>()
+      .x((d) => d.x)
+      .y((d) => d.yTop)
+      .curve(curveMonotoneX);
+    const topPathStr = topLineGenerator(validPoints) ?? '';
+
+    const topPoints = validPoints.map((p) => ({ x: p.x, y: p.yTop }));
+    const bottomPoints = validPoints.map((p) => ({ x: p.x, y: p.yBottom }));
+
+    const ariaLabel =
+      seriesKey === '__default__'
+        ? `Area with ${validPoints.length} data points`
+        : `${seriesKey}: area with ${validPoints.length} data points`;
+
+    const aria: MarkAria = { label: ariaLabel };
+
+    marks.push({
+      type: 'area',
+      topPoints,
+      bottomPoints,
+      path: pathStr,
+      topPath: topPathStr,
+      fill: color,
+      fillOpacity: DEFAULT_FILL_OPACITY,
+      stroke: color,
+      strokeWidth: 2,
+      seriesKey: seriesKey === '__default__' ? undefined : seriesKey,
+      data: validPoints.map((p) => p.row),
+      aria,
+    });
+  }
+
+  return marks;
+}
+
+// ---------------------------------------------------------------------------
+// Stacked area
+// ---------------------------------------------------------------------------
+
+function computeStackedArea(
+  spec: NormalizedChartSpec,
+  scales: ResolvedScales,
+  chartArea: Rect,
+): AreaMark[] {
+  const encoding = spec.encoding as Encoding;
+  const xChannel = encoding.x;
+  const yChannel = encoding.y;
+  const colorField = encoding.color?.field;
+
+  if (!xChannel || !yChannel || !scales.x || !scales.y || !colorField) {
+    // If no color field, can't stack -- fall back to single area
+    return computeSingleArea(spec, scales, chartArea);
+  }
+
+  // Collect unique series keys and x values, and build a lookup from
+  // (x-value, series-key) -> original data row so stacked area marks
+  // get original rows instead of pivot rows.
+  const seriesKeys = new Set<string>();
+  const xValueSet = new Set<string>();
+  const rowsByXSeries = new Map<string, DataRow>();
+  const rowsByX = new Map<string, DataRow[]>();
+
+  for (const row of spec.data) {
+    const xStr = String(row[xChannel.field]);
+    const series = String(row[colorField]);
+    seriesKeys.add(series);
+    xValueSet.add(xStr);
+    rowsByXSeries.set(`${xStr}::${series}`, row);
+
+    const existing = rowsByX.get(xStr);
+    if (existing) {
+      existing.push(row);
+    } else {
+      rowsByX.set(xStr, [row]);
+    }
+  }
+
+  const keys = Array.from(seriesKeys);
+  const xValues = Array.from(xValueSet);
+
+  // Build a pivot table: one row per x value, one column per series
+  const pivotData: Record<string, unknown>[] = xValues.map((xVal) => {
+    const pivot: Record<string, unknown> = { __x__: xVal };
+    for (const key of keys) {
+      pivot[key] = 0;
+    }
+    // Fill in actual values from pre-grouped data
+    const xRows = rowsByX.get(xVal);
+    if (xRows) {
+      for (const row of xRows) {
+        const series = String(row[colorField]);
+        pivot[series] = row[yChannel.field] ?? 0;
+      }
+    }
+    return pivot;
+  });
+
+  // Use d3 stack to compute the stacked layout
+  const stackGenerator = stack<Record<string, unknown>>()
+    .keys(keys)
+    .order(stackOrderNone)
+    .offset(stackOffsetNone);
+
+  const stackedData = stackGenerator(pivotData);
+  const yScale = scales.y.scale as ScaleLinear<number, number>;
+  const marks: AreaMark[] = [];
+
+  for (const layer of stackedData) {
+    const seriesKey = layer.key;
+    const color = getColor(scales, seriesKey);
+
+    const validPoints: { x: number; yTop: number; yBottom: number }[] = [];
+
+    for (const d of layer) {
+      const xVal = scaleValue(scales.x.scale, scales.x.type, d.data.__x__);
+
+      if (xVal === null) continue;
+
+      const yTop = yScale(d[1] as number);
+      const yBottom = yScale(d[0] as number);
+
+      validPoints.push({ x: xVal, yTop, yBottom });
+    }
+
+    if (validPoints.length === 0) continue;
+
+    const areaGenerator = area<{ x: number; yTop: number; yBottom: number }>()
+      .x((p) => p.x)
+      .y0((p) => p.yBottom)
+      .y1((p) => p.yTop)
+      .curve(curveMonotoneX);
+
+    const pathStr = areaGenerator(validPoints) ?? '';
+
+    const topLineGenerator = line<{ x: number; yTop: number }>()
+      .x((p) => p.x)
+      .y((p) => p.yTop)
+      .curve(curveMonotoneX);
+    const topPathStr = topLineGenerator(validPoints) ?? '';
+
+    const topPoints = validPoints.map((p) => ({ x: p.x, y: p.yTop }));
+    const bottomPoints = validPoints.map((p) => ({ x: p.x, y: p.yBottom }));
+
+    const aria: MarkAria = {
+      label: `${seriesKey}: stacked area with ${validPoints.length} data points`,
+    };
+
+    marks.push({
+      type: 'area',
+      topPoints,
+      bottomPoints,
+      path: pathStr,
+      topPath: topPathStr,
+      fill: color,
+      fillOpacity: 0.7, // Higher opacity for stacked so layers are visible
+      stroke: color,
+      strokeWidth: 1,
+      seriesKey,
+      data: layer.map((d) => {
+        const xStr = String(d.data.__x__);
+        return (rowsByXSeries.get(`${xStr}::${seriesKey}`) ?? d.data) as Record<string, unknown>;
+      }),
+      aria,
+    });
+  }
+
+  return marks;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * 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).
+ */
+export function computeAreaMarks(
+  spec: NormalizedChartSpec,
+  scales: ResolvedScales,
+  chartArea: Rect,
+): AreaMark[] {
+  const encoding = spec.encoding as Encoding;
+  const hasColor = !!encoding.color;
+
+  if (hasColor) {
+    return computeStackedArea(spec, scales, chartArea);
+  }
+
+  return computeSingleArea(spec, scales, chartArea);
+}

package/src/charts/line/compute.ts

@@ -0,0 +1,177 @@
+/**
+ * Line chart mark computation.
+ *
+ * Takes a normalized chart spec with resolved scales and produces
+ * LineMark[] and PointMark[] arrays for rendering. Groups data by
+ * color field for multi-series, uses D3 line() generator for SVG
+ * path computation, and handles missing data with line breaks.
+ */
+
+import type {
+  DataRow,
+  Encoding,
+  LayoutStrategy,
+  LineMark,
+  MarkAria,
+  PointMark,
+  Rect,
+} from '@opendata-ai/openchart-core';
+import { curveMonotoneX, line } from 'd3-shape';
+
+import type { NormalizedChartSpec } from '../../compiler/types';
+import type { ResolvedScales } from '../../layout/scales';
+import { getColor, groupByField, scaleValue } from '../utils';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/** Default stroke width for line marks. */
+const DEFAULT_STROKE_WIDTH = 2.5;
+
+/** Default radius for point marks (hover targets). */
+const DEFAULT_POINT_RADIUS = 3;
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute line marks from a normalized chart spec.
+ *
+ * Produces one LineMark per series (grouped by color field) plus
+ * PointMark entries at each data point for hover targets. Missing
+ * data (null/undefined y values) breaks the line path.
+ */
+export function computeLineMarks(
+  spec: NormalizedChartSpec,
+  scales: ResolvedScales,
+  _chartArea: Rect,
+  _strategy: LayoutStrategy,
+): (LineMark | PointMark)[] {
+  const encoding = spec.encoding as Encoding;
+  const xChannel = encoding.x;
+  const yChannel = encoding.y;
+
+  if (!xChannel || !yChannel || !scales.x || !scales.y) {
+    return [];
+  }
+
+  const colorField = encoding.color?.field;
+  const groups = groupByField(spec.data, colorField);
+  const marks: (LineMark | PointMark)[] = [];
+
+  for (const [seriesKey, rows] of groups) {
+    const color = getColor(scales, seriesKey);
+
+    // Compute pixel positions for each data point, preserving nulls
+    // for line break handling
+    const pointsWithData: {
+      x: number;
+      y: number;
+      row: DataRow;
+    }[] = [];
+
+    // We need to track segments separated by null values
+    const segments: { x: number; y: number }[][] = [];
+    let currentSegment: { x: number; y: number }[] = [];
+
+    for (const row of rows) {
+      const xVal = scaleValue(scales.x.scale, scales.x.type, row[xChannel.field]);
+      const yVal = scaleValue(scales.y.scale, scales.y.type, row[yChannel.field]);
+
+      if (xVal === null || yVal === null) {
+        // Break the line here. Push current segment if non-empty.
+        if (currentSegment.length > 0) {
+          segments.push(currentSegment);
+          currentSegment = [];
+        }
+        continue;
+      }
+
+      const point = { x: xVal, y: yVal };
+      currentSegment.push(point);
+      pointsWithData.push({ ...point, row });
+    }
+
+    // Push the last segment
+    if (currentSegment.length > 0) {
+      segments.push(currentSegment);
+    }
+
+    // Build the D3 line generator with monotone interpolation
+    const lineGenerator = line<{ x: number; y: number }>()
+      .x((d) => d.x)
+      .y((d) => d.y)
+      .curve(curveMonotoneX);
+
+    // Combine all segments into a single path string with M/L commands.
+    // Each segment starts a new M (moveto) command, creating line breaks
+    // where data is missing.
+    const allPoints: { x: number; y: number }[] = [];
+    const pathParts: string[] = [];
+
+    for (const segment of segments) {
+      if (segment.length === 0) continue;
+      const pathStr = lineGenerator(segment);
+      if (pathStr) {
+        pathParts.push(pathStr);
+      }
+      allPoints.push(...segment);
+    }
+
+    // Skip this series if there are no valid data points
+    if (allPoints.length === 0) continue;
+
+    const ariaLabel =
+      seriesKey === '__default__'
+        ? `Line with ${allPoints.length} data points`
+        : `${seriesKey}: line with ${allPoints.length} data points`;
+
+    const aria: MarkAria = {
+      label: ariaLabel,
+    };
+
+    // Combine D3 curve path segments into a single path string.
+    // Each segment produces a smooth monotone curve; line breaks between
+    // segments are created by starting a new M command.
+    const combinedPath = pathParts.join(' ');
+
+    // Create the LineMark with the combined path points.
+    // The points array includes all valid points across all segments.
+    const lineMark: LineMark = {
+      type: 'line',
+      points: allPoints,
+      path: combinedPath,
+      stroke: color,
+      strokeWidth: DEFAULT_STROKE_WIDTH,
+      seriesKey: seriesKey === '__default__' ? undefined : seriesKey,
+      data: pointsWithData.map((p) => p.row),
+      aria,
+    };
+
+    marks.push(lineMark);
+
+    // Create point marks for hover targets
+    for (let i = 0; i < pointsWithData.length; i++) {
+      const p = pointsWithData[i];
+      const pointMark: PointMark = {
+        type: 'point',
+        cx: p.x,
+        cy: p.y,
+        r: DEFAULT_POINT_RADIUS,
+        fill: color,
+        stroke: '#ffffff',
+        strokeWidth: 1.5,
+        fillOpacity: 0,
+        data: p.row,
+        aria: {
+          label: `Data point: ${xChannel.field}=${String(p.row[xChannel.field])}, ${yChannel.field}=${String(p.row[yChannel.field])}`,
+        },
+      };
+      marks.push(pointMark);
+    }
+  }
+
+  return marks;
+}

package/src/charts/line/index.ts

@@ -0,0 +1,68 @@
+/**
+ * Line & area chart module.
+ *
+ * Exports line and area chart renderers and computation functions.
+ */
+
+import type { LineMark, Mark } from '@opendata-ai/openchart-core';
+import type { ChartRenderer } from '../registry';
+import { computeAreaMarks } from './area';
+import { computeLineMarks } from './compute';
+import { computeLineLabels } from './labels';
+
+// ---------------------------------------------------------------------------
+// Line chart renderer
+// ---------------------------------------------------------------------------
+
+/**
+ * Line chart renderer.
+ *
+ * Computes line marks + point marks for hover targets, then resolves
+ * end-of-line labels and attaches them to the corresponding line marks.
+ */
+export const lineRenderer: ChartRenderer = (spec, scales, chartArea, strategy, _theme) => {
+  const marks = computeLineMarks(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);
+  for (const mark of marks) {
+    if (mark.type === 'line' && mark.seriesKey) {
+      const label = labelMap.get(mark.seriesKey);
+      if (label) {
+        mark.label = label;
+      }
+    }
+  }
+
+  return marks as Mark[];
+};
+
+// ---------------------------------------------------------------------------
+// Area chart renderer
+// ---------------------------------------------------------------------------
+
+/**
+ * Area chart renderer.
+ *
+ * Computes area fill marks (stacked if multi-series).
+ * Also computes line marks for the top boundary and point marks
+ * for hover targets, layered on top of the areas.
+ */
+export const areaRenderer: ChartRenderer = (spec, scales, chartArea, strategy, _theme) => {
+  const areas = computeAreaMarks(spec, scales, chartArea);
+  const lines = computeLineMarks(spec, scales, chartArea, strategy);
+
+  // Areas go first (rendered behind lines), then lines on top
+  return [...areas, ...lines] as Mark[];
+};
+
+// ---------------------------------------------------------------------------
+// Public exports
+// ---------------------------------------------------------------------------
+
+export { computeAreaMarks } from './area';
+export { computeLineMarks } from './compute';
+export { computeLineLabels } from './labels';

package/src/charts/line/labels.ts

@@ -0,0 +1,144 @@
+/**
+ * Line chart label computation.
+ *
+ * Produces end-of-line labels (series name at the last data point)
+ * and feeds them through the core collision engine. At compact
+ * breakpoints, labels are suppressed in favor of the legend.
+ *
+ * Respects the spec's label density setting:
+ * - 'all': show every label, skip collision detection
+ * - 'auto': existing behavior (collision detection)
+ * - 'endpoints': first and last data point labels per series
+ * - 'none': return empty map
+ */
+
+import type {
+  LabelCandidate,
+  LabelDensity,
+  LayoutStrategy,
+  LineMark,
+  ResolvedLabel,
+} from '@opendata-ai/openchart-core';
+import { estimateTextWidth, resolveCollisions } from '@opendata-ai/openchart-core';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/** Default label font size. */
+const LABEL_FONT_SIZE = 11;
+
+/** Default label font weight. */
+const LABEL_FONT_WEIGHT = 600;
+
+/** Horizontal offset from last point to label. */
+const LABEL_OFFSET_X = 6;
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute end-of-line labels for line marks.
+ *
+ * For each series, places a label at the position of the last data point.
+ * At compact breakpoints (labelMode === 'none'), all labels are hidden
+ * so the legend takes over. Labels go through collision detection to
+ * avoid overlap.
+ *
+ * Returns a Map keyed by seriesKey so callers can look up labels by
+ * mark identity instead of relying on positional indices.
+ *
+ * @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.
+ * @returns Map of seriesKey -> ResolvedLabel after collision detection.
+ */
+export function computeLineLabels(
+  marks: LineMark[],
+  strategy: LayoutStrategy,
+  density: LabelDensity = 'auto',
+  labelOffsets?: Record<string, { dx?: number; dy?: number }>,
+): Map<string, ResolvedLabel> {
+  const result = new Map<string, ResolvedLabel>();
+
+  // 'none': no labels
+  if (density === 'none') return result;
+
+  // At compact breakpoint, suppress inline labels entirely
+  if (strategy.labelMode === 'none') {
+    return result;
+  }
+
+  const candidates: LabelCandidate[] = [];
+  const seriesOrder: string[] = [];
+
+  for (const mark of marks) {
+    if (mark.points.length === 0) continue;
+
+    const labelText = mark.seriesKey ?? '';
+    if (!labelText) continue;
+
+    const lastPoint = mark.points[mark.points.length - 1];
+    const textWidth = estimateTextWidth(labelText, LABEL_FONT_SIZE, LABEL_FONT_WEIGHT);
+    const textHeight = LABEL_FONT_SIZE * 1.2;
+
+    candidates.push({
+      text: labelText,
+      anchorX: lastPoint.x + LABEL_OFFSET_X,
+      anchorY: lastPoint.y - textHeight / 2,
+      width: textWidth,
+      height: textHeight,
+      priority: 'data',
+      style: {
+        fontFamily: 'system-ui, -apple-system, sans-serif',
+        fontSize: LABEL_FONT_SIZE,
+        fontWeight: LABEL_FONT_WEIGHT,
+        fill: mark.stroke,
+        lineHeight: 1.2,
+        textAnchor: 'start',
+        dominantBaseline: 'central',
+      },
+    });
+
+    seriesOrder.push(labelText);
+  }
+
+  if (candidates.length === 0) return result;
+
+  // 'all': skip collision detection, mark everything visible
+  if (density === 'all') {
+    for (let i = 0; i < candidates.length; i++) {
+      const c = candidates[i];
+      const seriesKey = seriesOrder[i];
+      const userOffset = labelOffsets?.[seriesKey];
+      result.set(seriesKey, {
+        text: c.text,
+        x: c.anchorX + (userOffset?.dx ?? 0),
+        y: c.anchorY + (userOffset?.dy ?? 0),
+        style: c.style,
+        visible: true,
+      });
+    }
+    return result;
+  }
+
+  // 'endpoints': for line charts, endpoints means showing just the end-of-line
+  // label (which is what we already compute). This is the same as 'auto' for lines
+  // since we only compute the endpoint label per series.
+
+  const resolved = resolveCollisions(candidates);
+  for (let i = 0; i < resolved.length; i++) {
+    const seriesKey = seriesOrder[i];
+    const label = resolved[i];
+    // Apply user-provided per-series label offset after collision resolution
+    const userOffset = labelOffsets?.[seriesKey];
+    if (userOffset) {
+      label.x += userOffset.dx ?? 0;
+      label.y += userOffset.dy ?? 0;
+    }
+    result.set(seriesKey, label);
+  }
+
+  return result;
+}