@opendata-ai/openchart-engine 8.0.0-rc.12 → 8.0.0-rc.3

package/src/charts/dot/__tests__/labels.test.ts

@@ -0,0 +1,98 @@
+import type { PointMark } from '@opendata-ai/openchart-core';
+import { describe, expect, it } from 'vitest';
+import { computeDotLabels } from '../labels';
+
+// ---------------------------------------------------------------------------
+// Fixtures
+// ---------------------------------------------------------------------------
+
+const chartArea = { x: 0, y: 0, width: 400, height: 300 };
+
+function makeMark(index: number, value: number): PointMark {
+  return {
+    type: 'point',
+    cx: value * 5,
+    cy: index * 40 + 20,
+    r: 6,
+    fill: '#4e79a7',
+    stroke: '#4e79a7',
+    strokeWidth: 1,
+    data: { category: `Cat${index}`, value },
+    aria: { label: `Cat${index}: ${value}` },
+  };
+}
+
+const marks: PointMark[] = [
+  makeMark(0, 10),
+  makeMark(1, 20),
+  makeMark(2, 30),
+  makeMark(3, 40),
+  makeMark(4, 50),
+];
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('computeDotLabels density modes', () => {
+  it('density "auto" runs collision detection and produces labels', () => {
+    const labels = computeDotLabels(marks, chartArea, 'auto');
+    expect(labels.length).toBeGreaterThan(0);
+    expect(labels.every((l) => typeof l.visible === 'boolean')).toBe(true);
+  });
+
+  it('density "all" shows every label as visible', () => {
+    const labels = computeDotLabels(marks, chartArea, 'all');
+    expect(labels).toHaveLength(marks.length);
+    expect(labels.every((l) => l.visible === true)).toBe(true);
+  });
+
+  it('density "none" returns empty array', () => {
+    const labels = computeDotLabels(marks, chartArea, 'none');
+    expect(labels).toHaveLength(0);
+  });
+
+  it('density "endpoints" returns only first and last labels', () => {
+    const labels = computeDotLabels(marks, chartArea, 'endpoints');
+    expect(labels).toHaveLength(2);
+    expect(labels[0].text).toBe('10');
+    expect(labels[1].text).toBe('50');
+  });
+
+  it('density "endpoints" with single mark returns that mark', () => {
+    const labels = computeDotLabels([marks[0]], chartArea, 'endpoints');
+    expect(labels).toHaveLength(1);
+    expect(labels[0].text).toBe('10');
+  });
+
+  it('default density is "auto"', () => {
+    const withAuto = computeDotLabels(marks, chartArea, 'auto');
+    const withDefault = computeDotLabels(marks, chartArea);
+    expect(withDefault.length).toBe(withAuto.length);
+  });
+});
+
+describe('computeDotLabels positioning', () => {
+  it('places labels to the right of the dot', () => {
+    const labels = computeDotLabels([marks[0]], chartArea, 'all');
+    expect(labels).toHaveLength(1);
+    // Label x should be to the right of the dot center + radius
+    expect(labels[0].x).toBeGreaterThan(marks[0].cx + marks[0].r);
+  });
+
+  it('vertically centers labels on the dot', () => {
+    const labels = computeDotLabels([marks[0]], chartArea, 'all');
+    const textHeight = 11 * 1.2; // LABEL_FONT_SIZE * 1.2
+    // Label y should be roughly centered on the dot's cy
+    expect(labels[0].y).toBeCloseTo(marks[0].cy - textHeight / 2, 0);
+  });
+
+  it('returns empty for marks with no parseable value', () => {
+    const badMark: PointMark = {
+      ...marks[0],
+      aria: { label: 'no-colon-here' },
+    };
+    const labels = computeDotLabels([badMark], chartArea, 'all');
+    expect(labels).toHaveLength(0);
+  });
+});

package/src/charts/dot/compute.ts

@@ -0,0 +1,285 @@
+/**
+ * Dot plot / lollipop chart mark computation.
+ *
+ * Category axis (band scale) + value axis (linear scale). Produces
+ * PointMark[] for the dots plus RectMark[] for lollipop stems
+ * (thin lines from axis baseline to each dot).
+ *
+ * When a color encoding is present (multi-series), renders as a dumbbell
+ * chart: a connecting bar spans min-to-max per category instead of
+ * baseline-to-dot stems.
+ */
+
+import type {
+  Encoding,
+  LayoutStrategy,
+  MarkAria,
+  PointMark,
+  Rect,
+  RectMark,
+} from '@opendata-ai/openchart-core';
+import type { ScaleBand, ScaleLinear } from 'd3-scale';
+
+import { dedupeKeys, serializeKeyValue } from '../../compiler/keys';
+import type { NormalizedChartSpec } from '../../compiler/types';
+import type { ResolvedScales } from '../../layout/scales';
+import { getColor, getSequentialColor, groupByField } from '../utils';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const DOT_RADIUS = 6;
+const STEM_WIDTH = 2;
+const STEM_COLOR = '#cccccc';
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute dot plot marks from a normalized chart spec.
+ *
+ * Y axis uses a band scale for categories. X axis uses a linear scale
+ * for values. When no color encoding is present, each data point produces
+ * a lollipop stem + dot. When color is present (multi-series), renders
+ * connecting bars between min/max values per category (dumbbell style).
+ */
+export function computeDotMarks(
+  spec: NormalizedChartSpec,
+  scales: ResolvedScales,
+  _chartArea: Rect,
+  _strategy: LayoutStrategy,
+): (PointMark | RectMark)[] {
+  const encoding = spec.encoding as Encoding;
+  const xChannel = encoding.x;
+  const yChannel = encoding.y;
+
+  if (!xChannel || !yChannel || !scales.x || !scales.y) {
+    return [];
+  }
+
+  const xScale = scales.x.scale as ScaleLinear<number, number>;
+  const yScale = scales.y.scale as ScaleBand<string>;
+
+  // Band scale should provide bandwidth
+  if (typeof yScale.bandwidth !== 'function') {
+    return [];
+  }
+
+  const bandwidth = yScale.bandwidth();
+  // Clamp baseline to the scale range so stems never extend past the plot area
+  // (e.g., when domain doesn't include zero, xScale(0) would land outside).
+  const [rangeStart, rangeEnd] = xScale.range();
+  const rangeMin = Math.min(rangeStart, rangeEnd);
+  const rangeMax = Math.max(rangeStart, rangeEnd);
+  const baseline = Math.max(rangeMin, Math.min(rangeMax, xScale(0)));
+  const colorEnc = encoding.color && 'field' in encoding.color ? encoding.color : undefined;
+  const isSequentialColor = colorEnc?.type === 'quantitative';
+  const colorField = isSequentialColor ? undefined : colorEnc?.field;
+
+  let marks: (PointMark | RectMark)[];
+
+  // Multi-series (categorical): dumbbell chart with connecting bars
+  if (colorField) {
+    marks = computeDumbbellMarks(
+      spec.data,
+      xChannel.field,
+      yChannel.field,
+      colorField,
+      xScale,
+      yScale,
+      bandwidth,
+      scales,
+    );
+  } else {
+    // Single series: lollipop stems from baseline
+    marks = computeLollipopMarks(
+      spec.data,
+      xChannel.field,
+      yChannel.field,
+      xScale,
+      yScale,
+      bandwidth,
+      baseline,
+      scales,
+      isSequentialColor,
+    );
+  }
+
+  // Stamp keys on point marks (skip rect stems/connectors)
+  const pointMarks = marks.filter((m): m is PointMark => m.type === 'point');
+  const rawKeys = pointMarks.map((m) => {
+    const cat = serializeKeyValue(m.data[yChannel.field]);
+    const series = colorField ? String(m.data[colorField] ?? '') : '';
+    return series ? `${series}|${cat}` : cat;
+  });
+  const keys = dedupeKeys(rawKeys);
+  for (let i = 0; i < pointMarks.length; i++) {
+    pointMarks[i].key = keys[i];
+  }
+
+  return marks;
+}
+
+// ---------------------------------------------------------------------------
+// Dumbbell (multi-series)
+// ---------------------------------------------------------------------------
+
+/** Compute dumbbell marks: connecting bar + colored dots per category. */
+function computeDumbbellMarks(
+  data: readonly Record<string, unknown>[],
+  valueField: string,
+  categoryField: string,
+  colorField: string,
+  xScale: ScaleLinear<number, number>,
+  yScale: ScaleBand<string>,
+  bandwidth: number,
+  scales: ResolvedScales,
+): (PointMark | RectMark)[] {
+  const marks: (PointMark | RectMark)[] = [];
+  const categoryGroups = groupByField([...data], categoryField);
+
+  for (const [category, rows] of categoryGroups) {
+    const bandY = yScale(category);
+    if (bandY === undefined) continue;
+
+    const cy = bandY + bandwidth / 2;
+
+    // Collect all x-values for this category to find the range
+    const xValues: number[] = [];
+    for (const row of rows) {
+      const value = Number(row[valueField] ?? 0);
+      if (Number.isFinite(value)) xValues.push(value);
+    }
+
+    if (xValues.length === 0) continue;
+
+    const minVal = Math.min(...xValues);
+    const maxVal = Math.max(...xValues);
+    const xLeft = xScale(minVal);
+    const xRight = xScale(maxVal);
+    const barWidth = Math.abs(xRight - xLeft);
+
+    // Connecting bar (rendered first so dots layer on top)
+    if (barWidth > 0) {
+      const stemAria: MarkAria = {
+        label: `Range for ${category}: ${minVal} to ${maxVal}`,
+      };
+
+      marks.push({
+        type: 'rect',
+        x: Math.min(xLeft, xRight),
+        y: cy - STEM_WIDTH / 2,
+        width: barWidth,
+        height: STEM_WIDTH,
+        fill: STEM_COLOR,
+        data: rows[0] as Record<string, unknown>,
+        aria: stemAria,
+      });
+    }
+
+    // Individual dots for each series value
+    for (const row of rows) {
+      const value = Number(row[valueField] ?? 0);
+      if (!Number.isFinite(value)) continue;
+
+      const cx = xScale(value);
+      const colorCategory = String(row[colorField] ?? '');
+      const color = getColor(scales, colorCategory);
+
+      const dotAria: MarkAria = {
+        label: `${category}, ${colorCategory}: ${value}`,
+      };
+
+      marks.push({
+        type: 'point',
+        cx,
+        cy,
+        r: DOT_RADIUS,
+        fill: color,
+        stroke: '#ffffff',
+        strokeWidth: 2,
+        data: row as Record<string, unknown>,
+        aria: dotAria,
+      });
+    }
+  }
+
+  return marks;
+}
+
+// ---------------------------------------------------------------------------
+// Lollipop (single series)
+// ---------------------------------------------------------------------------
+
+/** Compute lollipop marks: stem from baseline + dot. */
+function computeLollipopMarks(
+  data: readonly Record<string, unknown>[],
+  valueField: string,
+  categoryField: string,
+  xScale: ScaleLinear<number, number>,
+  yScale: ScaleBand<string>,
+  bandwidth: number,
+  baseline: number,
+  scales: ResolvedScales,
+  isSequentialColor = false,
+): (PointMark | RectMark)[] {
+  const marks: (PointMark | RectMark)[] = [];
+
+  for (const row of data) {
+    const category = String(row[categoryField] ?? '');
+    const value = Number(row[valueField] ?? 0);
+    if (!Number.isFinite(value)) continue;
+
+    const bandY = yScale(category);
+    if (bandY === undefined) continue;
+
+    const cx = xScale(value);
+    const cy = bandY + bandwidth / 2;
+
+    const color = isSequentialColor
+      ? getSequentialColor(scales, value)
+      : getColor(scales, '__default__');
+
+    // Stem: thin rectangle from baseline to dot center
+    const stemX = Math.min(baseline, cx);
+    const stemWidth = Math.abs(cx - baseline);
+
+    if (stemWidth > 0) {
+      const stemAria: MarkAria = {
+        label: `Stem for ${category}`,
+      };
+
+      marks.push({
+        type: 'rect',
+        x: stemX,
+        y: cy - STEM_WIDTH / 2,
+        width: stemWidth,
+        height: STEM_WIDTH,
+        fill: STEM_COLOR,
+        data: row as Record<string, unknown>,
+        aria: stemAria,
+      });
+    }
+
+    // Dot
+    const dotAria: MarkAria = {
+      label: `${category}: ${value}`,
+    };
+
+    marks.push({
+      type: 'point',
+      cx,
+      cy,
+      r: DOT_RADIUS,
+      fill: color,
+      stroke: '#ffffff',
+      strokeWidth: 2,
+      data: row as Record<string, unknown>,
+      aria: dotAria,
+    });
+  }
+
+  return marks;
+}

package/src/charts/dot/index.ts

@@ -0,0 +1,62 @@
+/**
+ * Dot plot / lollipop chart module.
+ *
+ * Exports the dot chart renderer and computation functions.
+ */
+
+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';
+
+// ---------------------------------------------------------------------------
+// Dot chart renderer
+// ---------------------------------------------------------------------------
+
+/**
+ * Dot/lollipop chart renderer.
+ *
+ * Produces stem (RectMark) and dot (PointMark) pairs for each data point.
+ * Value labels are attached to the dot marks.
+ */
+export const dotRenderer: ChartRenderer = (spec, scales, chartArea, strategy, _theme) => {
+  const marks = computeDotMarks(spec, scales, chartArea, strategy);
+
+  // Extract just the point marks for label computation
+  const pointMarks = marks.filter((m): m is PointMark => m.type === 'point');
+
+  // 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,
+    labelFormatter,
+    valueField,
+  );
+  let labelIdx = 0;
+  for (const mark of marks) {
+    if (mark.type === 'point' && labelIdx < labels.length) {
+      mark.label = labels[labelIdx];
+      labelIdx++;
+    }
+  }
+
+  return marks as Mark[];
+};
+
+// ---------------------------------------------------------------------------
+// Public exports
+// ---------------------------------------------------------------------------
+
+export { computeDotMarks } from './compute';
+export { computeDotLabels } from './labels';

package/src/charts/dot/labels.ts

@@ -0,0 +1,121 @@
+/**
+ * Dot chart label computation.
+ *
+ * Produces value labels positioned to the right of each dot.
+ *
+ * Respects the spec's label density setting:
+ * - 'all': show every label, skip collision detection
+ * - 'auto': existing behavior (collision detection)
+ * - 'endpoints': first and last dots only
+ * - 'none': return empty array
+ */
+
+import type {
+  LabelCandidate,
+  LabelDensity,
+  NumberFormatter,
+  PointMark,
+  Rect,
+  ResolvedLabel,
+} from '@opendata-ai/openchart-core';
+import {
+  estimateTextWidth,
+  getRepresentativeColor,
+  resolveCollisions,
+} from '@opendata-ai/openchart-core';
+import { filterByDensity } from '../_shared/density-filter';
+import { formatLabelValue } from '../_shared/format-label-value';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const LABEL_FONT_SIZE = 11;
+const LABEL_FONT_WEIGHT = 600;
+const LABEL_OFFSET_X = 10;
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute value labels for dot marks.
+ *
+ * Places labels to the right of each dot point.
+ */
+export function computeDotLabels(
+  marks: PointMark[],
+  _chartArea: Rect,
+  density: LabelDensity = 'auto',
+  labelPrefix?: string,
+  labelFormatter?: NumberFormatter | null,
+  valueField?: string,
+): ResolvedLabel[] {
+  const targetMarks = filterByDensity(marks, density);
+
+  const formatter = labelFormatter ?? null;
+  const candidates: LabelCandidate[] = [];
+
+  for (const mark of targetMarks) {
+    // Get the original numeric value from the data row when possible,
+    // falling back to parsing the aria label (which may lose precision
+    // due to abbreviation rounding, e.g. 1955 → "2K" → 2000).
+    let valuePart: string;
+    const rawNum = valueField != null ? Number(mark.data[valueField]) : NaN;
+
+    if (formatter && Number.isFinite(rawNum)) {
+      valuePart = formatter(rawNum);
+    } else if (Number.isFinite(rawNum)) {
+      valuePart = formatLabelValue(rawNum);
+    } 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;
+      if (formatter) {
+        const num = Number(valuePart.replace(/[^0-9.-]/g, ''));
+        if (!Number.isNaN(num)) valuePart = formatter(num);
+      }
+    }
+    if (labelPrefix) valuePart = labelPrefix + valuePart;
+
+    const textWidth = estimateTextWidth(valuePart, LABEL_FONT_SIZE, LABEL_FONT_WEIGHT);
+    const textHeight = LABEL_FONT_SIZE * 1.2;
+
+    candidates.push({
+      text: valuePart,
+      anchorX: mark.cx + mark.r + LABEL_OFFSET_X,
+      anchorY: mark.cy - 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: getRepresentativeColor(mark.fill),
+        lineHeight: 1.2,
+        textAnchor: 'start',
+        dominantBaseline: 'central',
+        fontVariant: 'tabular-nums',
+      },
+    });
+  }
+
+  if (candidates.length === 0) return [];
+
+  // 'all': skip collision detection, mark everything visible
+  if (density === 'all') {
+    return candidates.map((c) => ({
+      text: c.text,
+      x: c.anchorX,
+      y: c.anchorY,
+      style: c.style,
+      visible: true,
+    }));
+  }
+
+  return resolveCollisions(candidates);
+}