@opendata-ai/openchart-engine 8.0.0-rc.9 → 8.1.0

package/src/charts/line/compute.ts

@@ -1,356 +0,0 @@
-/**
- * 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,
-  GradientDef,
-  LayoutStrategy,
-  LineMark,
-  MarkAria,
-  PointMark,
-  Rect,
-} from '@opendata-ai/openchart-core';
-import { getRepresentativeColor } from '@opendata-ai/openchart-core';
-import { line } from 'd3-shape';
-
-import { dedupeKeys, serializeKeyValue } from '../../compiler/keys';
-import type { NormalizedChartSpec } from '../../compiler/types';
-import type { ResolvedScales } from '../../layout/scales';
-import { getColor, getSequentialColor, groupByField, scaleValue, sortByField } from '../utils';
-import { resolveCurve } from './curves';
-
-// ---------------------------------------------------------------------------
-// Constants
-// ---------------------------------------------------------------------------
-
-/** 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;
-
-/** 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
-// ---------------------------------------------------------------------------
-
-/**
- * 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 colorEnc = encoding.color && 'field' in encoding.color ? encoding.color : undefined;
-  const isSequentialColor = colorEnc?.type === 'quantitative';
-  // Sequential color: single series, per-point coloring. Categorical: group by color field.
-  const colorField = isSequentialColor ? undefined : colorEnc?.field;
-  const sequentialColorField = isSequentialColor ? colorEnc.field : undefined;
-  // 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 ?? [];
-  const highlightActive = highlight.length > 0;
-
-  for (const [seriesKey, rows] of groups) {
-    // For sequential color, use a mid-range color for the line stroke
-    const color: string | GradientDef = isSequentialColor
-      ? getSequentialColor(scales, _getMidValue(rows, sequentialColorField!))
-      : getColor(scales, seriesKey);
-    // 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
-    // natural sort and the scale domain already reflects intended order.
-    const sortedRows =
-      xChannel.type === 'nominal' || xChannel.type === 'ordinal'
-        ? rows
-        : sortByField(rows, xChannel.field);
-
-    // 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 sortedRows) {
-      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 configured interpolation
-    const curve = resolveCurve(spec.markDef.interpolate);
-    const lineGenerator = line<{ x: number; y: number }>()
-      .x((d) => d.x)
-      .y((d) => d.y)
-      .curve(curve);
-
-    // 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(' ');
-
-    // Look up per-series style overrides
-    const seriesStyleKey = seriesKey === '__default__' ? undefined : seriesKey;
-    const styleOverride = seriesStyleKey ? spec.seriesStyles?.[seriesStyleKey] : undefined;
-
-    const isMuted = highlightActive && !highlight.includes(seriesKey);
-    let resolvedStrokeWidth =
-      styleOverride?.strokeWidth ?? spec.markDef.strokeWidth ?? DEFAULT_STROKE_WIDTH;
-    if (isMuted) {
-      resolvedStrokeWidth = Math.max(1, resolvedStrokeWidth * 0.75);
-    }
-
-    // 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.
-    // dataPoints carries pixel coordinates + original data for voronoi tooltip overlay.
-    const keyField = encoding.key && 'field' in encoding.key ? encoding.key.field : undefined;
-    const rawPointKeys = pointsWithData.map((p) =>
-      keyField ? serializeKeyValue(p.row[keyField]) : serializeKeyValue(p.row[xChannel.field]),
-    );
-
-    const lineMark: LineMark = {
-      type: 'line',
-      key: seriesStyleKey ?? 'series',
-      pointKeys: dedupeKeys(rawPointKeys),
-      interpolate: spec.markDef.interpolate ?? 'monotone',
-      points: allPoints,
-      path: combinedPath,
-      stroke: strokeColor,
-      strokeWidth: resolvedStrokeWidth,
-      strokeDasharray,
-      opacity: styleOverride?.opacity,
-      seriesKey: seriesStyleKey,
-      data: pointsWithData.map((p) => p.row),
-      dataPoints: pointsWithData.map((p) => ({ x: p.x, y: p.y, datum: p.row })),
-      aria,
-    };
-
-    const bucket = isMuted ? mutedMarks : highlightedMarks;
-    bucket.push(lineMark);
-
-    // 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) {
-      const isTransparent = markPoint === 'transparent';
-      const isEndpoints = markPoint === 'endpoints';
-      // Also respect per-series showPoints override
-      const seriesShowPoints = styleOverride?.showPoints !== false;
-      const lastIdx = pointsWithData.length - 1;
-
-      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;
-        if (isSequentialColor) {
-          const val = Number(p.row[sequentialColorField!]);
-          pointColor = Number.isFinite(val) ? getSequentialColor(scales, val) : color;
-        }
-        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.
-        const pointKey = keyField
-          ? serializeKeyValue(p.row[keyField])
-          : seriesStyleKey
-            ? `${seriesStyleKey}|${serializeKeyValue(p.row[xChannel.field])}`
-            : serializeKeyValue(p.row[xChannel.field]);
-        if (isSingleEndpoint) {
-          bucket.push({
-            type: 'point',
-            key: pointKey,
-            cx: p.x,
-            cy: p.y,
-            r: 3.5,
-            fill: strokeColor,
-            stroke: 'transparent',
-            strokeWidth: 0,
-            fillOpacity: 1,
-            data: p.row,
-            aria: { decorative: true },
-          });
-          continue;
-        }
-        const pointMark: PointMark = {
-          type: 'point',
-          key: pointKey,
-          cx: p.x,
-          cy: p.y,
-          r: visible ? DEFAULT_POINT_RADIUS : 0,
-          fill: hollow ? 'transparent' : pointColorStr,
-          stroke: hollow ? pointColorStr : visible ? '#ffffff' : 'transparent',
-          strokeWidth: visible ? 1.5 : 0,
-          fillOpacity: isTransparent ? 0 : 1,
-          data: p.row,
-          aria: {
-            label: `Data point: ${xChannel.field}=${String(p.row[xChannel.field])}, ${yChannel.field}=${String(p.row[yChannel.field])}`,
-          },
-        };
-        bucket.push(pointMark);
-      }
-    }
-  }
-
-  const allMarks = [...mutedMarks, ...highlightedMarks];
-
-  // Dedupe series-level keys across all line marks
-  const lineMarks = allMarks.filter((m): m is LineMark => m.type === 'line');
-  const lineKeys = dedupeKeys(lineMarks.map((m) => m.key!));
-  lineMarks.forEach((m, i) => {
-    m.key = lineKeys[i];
-  });
-
-  // Dedupe point mark keys
-  const pointMarks = allMarks.filter((m): m is PointMark => m.type === 'point');
-  if (pointMarks.length > 0) {
-    const pointKeys = dedupeKeys(pointMarks.map((m) => m.key ?? ''));
-    pointMarks.forEach((m, i) => {
-      m.key = pointKeys[i];
-    });
-  }
-
-  return allMarks;
-}
-
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-/** Get the midpoint numeric value of a field across rows (for sequential line stroke). */
-function _getMidValue(rows: DataRow[], field: string): number {
-  const values = rows.map((r) => Number(r[field])).filter(Number.isFinite);
-  if (values.length === 0) return 0;
-  const sorted = values.sort((a, b) => a - b);
-  return sorted[Math.floor(sorted.length / 2)];
-}

package/src/charts/line/curves.ts

@@ -1,85 +0,0 @@
-/**
- * Curve interpolation mapping and path builders.
- *
- * Maps Vega-Lite-style interpolation strings to d3-shape curve factories.
- * Used by both line and area chart computations.
- *
- * Also exports pure path-builder helpers (`buildLinePath`, `buildAreaPath`)
- * so downstream consumers (e.g. transition interpolators) can reconstruct
- * SVG paths from point arrays without pulling in chart-specific code.
- */
-
-import type { MarkDef, Point } from '@opendata-ai/openchart-core';
-import type { CurveFactory } from 'd3-shape';
-import {
-  area,
-  curveBasis,
-  curveCardinal,
-  curveLinear,
-  curveMonotoneX,
-  curveNatural,
-  curveStep,
-  curveStepAfter,
-  curveStepBefore,
-  line,
-} from 'd3-shape';
-
-/** Map of interpolation string names to d3 curve factories. */
-const CURVE_MAP: Record<NonNullable<MarkDef['interpolate']>, CurveFactory> = {
-  linear: curveLinear,
-  monotone: curveMonotoneX,
-  step: curveStep,
-  'step-before': curveStepBefore,
-  'step-after': curveStepAfter,
-  basis: curveBasis,
-  cardinal: curveCardinal,
-  natural: curveNatural,
-};
-
-/**
- * Resolve an interpolation string to a d3 curve factory.
- * Defaults to `curveMonotoneX` when no interpolation is specified.
- */
-export function resolveCurve(interpolate?: MarkDef['interpolate']): CurveFactory {
-  if (!interpolate) return curveMonotoneX;
-  return CURVE_MAP[interpolate] ?? curveMonotoneX;
-}
-
-/**
- * Build an SVG path string from an array of points using d3 line generator.
- * Accepts an optional interpolation string (defaults to 'monotone').
- */
-export function buildLinePath(points: Point[], interpolate?: string): string {
-  if (points.length === 0) return '';
-  const curve = resolveCurve(interpolate as MarkDef['interpolate']);
-  const generator = line<Point>()
-    .x((d) => d.x)
-    .y((d) => d.y)
-    .curve(curve);
-  return generator(points) ?? '';
-}
-
-/**
- * Build an SVG path string for a filled area from top and bottom point arrays.
- * Accepts an optional interpolation string (defaults to 'monotone').
- */
-export function buildAreaPath(
-  topPoints: Point[],
-  bottomPoints: Point[],
-  interpolate?: string,
-): string {
-  if (topPoints.length === 0) return '';
-  const curve = resolveCurve(interpolate as MarkDef['interpolate']);
-  // Pair top and bottom points for the area generator
-  const paired = topPoints.map((tp, i) => ({
-    x: tp.x,
-    yTop: tp.y,
-    yBottom: bottomPoints[i]?.y ?? 0,
-  }));
-  const generator = area<{ x: number; yTop: number; yBottom: number }>()
-    .x((d) => d.x)
-    .y0((d) => d.yBottom)
-    .y1((d) => d.yTop)
-    .curve(curve);
-  return generator(paired) ?? '';
-}

package/src/charts/line/index.ts

@@ -1,176 +0,0 @@
-/**
- * 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, PointMark } from '@opendata-ai/openchart-core';
-import { getRepresentativeColor } from '@opendata-ai/openchart-core';
-import type { NormalizedChartSpec } from '../../compiler/types';
-import type { ChartRenderer } from '../registry';
-import { computeAreaMarks } from './area';
-import { computeLineMarks } from './compute';
-import { computeLineLabels } from './labels';
-
-/** Radius for area-chart data points, matching the line renderer. */
-const AREA_POINT_RADIUS = 3;
-
-// ---------------------------------------------------------------------------
-// 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. 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);
-      if (label) {
-        mark.label = label;
-      }
-    }
-  }
-
-  return marks as Mark[];
-};
-
-// ---------------------------------------------------------------------------
-// Area chart renderer
-// ---------------------------------------------------------------------------
-
-/**
- * Area chart renderer.
- *
- * 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, theme.isDark);
-
-  const encoding = spec.encoding;
-  const hasColor = !!(encoding.color && 'field' in encoding.color);
-
-  // 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);
-
-  // For multi-series areas the lines are derived from area tops, which skips
-  // the point-emission path in computeLineMarks. Emit the data-point dots here
-  // so `mark.point` works on area charts the same way it does on lines.
-  // Single-series areas already get their points from computeLineMarks above.
-  const points = hasColor && spec.markDef.point ? pointsFromAreas(areas, spec.markDef.point) : [];
-
-  // Areas go first (rendered behind lines), then lines, then points on top
-  return [...areas, ...lines, ...points] as Mark[];
-};
-
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-/**
- * 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) => ({
-    type: 'line' as const,
-    points: a.topPoints,
-    path: a.topPath,
-    stroke: getRepresentativeColor(a.fill),
-    strokeWidth: a.strokeWidth ?? 1,
-    seriesKey: a.seriesKey,
-    data: a.data,
-    dataPoints: a.dataPoints,
-    aria: { label: `${a.seriesKey ?? 'Series'}: line with ${a.topPoints.length} data points` },
-  }));
-}
-
-/**
- * Derive PointMark[] sitting on each area's top boundary. Honors the same
- * `mark.point` modes as the line renderer: `true` (filled dots), `'transparent'`
- * (invisible hover targets), and `'endpoints'` (hollow dots at first/last only).
- */
-function pointsFromAreas(
-  areas: AreaMark[],
-  pointMode: NonNullable<NormalizedChartSpec['markDef']['point']>,
-): PointMark[] {
-  const isTransparent = pointMode === 'transparent';
-  const isEndpoints = pointMode === 'endpoints';
-  const points: PointMark[] = [];
-
-  for (const a of areas) {
-    const stroke = getRepresentativeColor(a.fill);
-    const lastIdx = a.topPoints.length - 1;
-
-    for (let i = 0; i < a.topPoints.length; i++) {
-      const pt = a.topPoints[i];
-      const isEndpoint = i === 0 || i === lastIdx;
-      const visible = !isTransparent && (!isEndpoints || isEndpoint);
-      const hollow = isEndpoints && visible;
-      points.push({
-        type: 'point',
-        cx: pt.x,
-        cy: pt.y,
-        r: visible ? AREA_POINT_RADIUS : 0,
-        fill: hollow ? 'transparent' : stroke,
-        stroke: hollow ? stroke : visible ? '#ffffff' : 'transparent',
-        strokeWidth: visible ? 1.5 : 0,
-        fillOpacity: isTransparent ? 0 : 1,
-        data: a.data[i] ?? {},
-        aria: { decorative: true },
-      });
-    }
-  }
-
-  return points;
-}
-
-// ---------------------------------------------------------------------------
-// Public exports
-// ---------------------------------------------------------------------------
-
-export { computeAreaMarks } from './area';
-export { computeLineMarks } from './compute';
-export { computeLineLabels } from './labels';