@opendata-ai/openchart-engine 1.2.0

package/src/charts/column/index.ts

@@ -0,0 +1,33 @@
+/**
+ * Column chart module (vertical bars).
+ *
+ * Exports the column chart renderer and computation functions.
+ */
+
+import type { Mark } from '@opendata-ai/openchart-core';
+import type { ChartRenderer } from '../registry';
+import { computeColumnMarks } from './compute';
+import { computeColumnLabels } from './labels';
+
+// ---------------------------------------------------------------------------
+// Column chart renderer
+// ---------------------------------------------------------------------------
+
+export const columnRenderer: ChartRenderer = (spec, scales, chartArea, strategy, _theme) => {
+  const marks = computeColumnMarks(spec, scales, chartArea, strategy);
+
+  // Compute and attach value labels (respects spec.labels.density)
+  const labels = computeColumnLabels(marks, chartArea, spec.labels.density);
+  for (let i = 0; i < marks.length && i < labels.length; i++) {
+    marks[i].label = labels[i];
+  }
+
+  return marks as Mark[];
+};
+
+// ---------------------------------------------------------------------------
+// Public exports
+// ---------------------------------------------------------------------------
+
+export { computeColumnMarks } from './compute';
+export { computeColumnLabels } from './labels';

package/src/charts/column/labels.ts

@@ -0,0 +1,108 @@
+/**
+ * Column chart label computation.
+ *
+ * Produces value labels positioned above each column (for positive values)
+ * or below (for negative values).
+ *
+ * Respects the spec's label density setting:
+ * - 'all': show every label, skip collision detection
+ * - 'auto': existing behavior (collision detection)
+ * - 'endpoints': first and last columns only
+ * - 'none': return empty array
+ */
+
+import type {
+  LabelCandidate,
+  LabelDensity,
+  RectMark,
+  ResolvedLabel,
+} from '@opendata-ai/openchart-core';
+import { estimateTextWidth, resolveCollisions } from '@opendata-ai/openchart-core';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const LABEL_FONT_SIZE = 10;
+const LABEL_FONT_WEIGHT = 600;
+const LABEL_OFFSET_Y = 6;
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute value labels for column marks.
+ *
+ * For each column, the value is placed centered above the column top.
+ */
+export function computeColumnLabels(
+  marks: RectMark[],
+  _chartArea: { x: number; y: number; width: number; height: number },
+  density: LabelDensity = 'auto',
+): ResolvedLabel[] {
+  // 'none': no labels at all
+  if (density === 'none') return [];
+
+  // Filter marks for 'endpoints' density
+  const targetMarks =
+    density === 'endpoints' && marks.length > 1 ? [marks[0], marks[marks.length - 1]] : marks;
+
+  const candidates: LabelCandidate[] = [];
+
+  for (const mark of targetMarks) {
+    // Extract the display value from the aria label.
+    // Format is "category: value" or "category, group: value".
+    // Use the last colon to split, which handles colons in category names.
+    const ariaLabel = mark.aria.label;
+    const lastColon = ariaLabel.lastIndexOf(':');
+    const valuePart = lastColon >= 0 ? ariaLabel.slice(lastColon + 1).trim() : '';
+    if (!valuePart) continue;
+
+    const numericValue = parseFloat(valuePart);
+    const isNegative = Number.isFinite(numericValue) && numericValue < 0;
+
+    const textWidth = estimateTextWidth(valuePart, LABEL_FONT_SIZE, LABEL_FONT_WEIGHT);
+    const textHeight = LABEL_FONT_SIZE * 1.2;
+
+    // For positive values, place label above the column top.
+    // For negative values, place label below the column bottom.
+    const anchorX = mark.x + mark.width / 2 - textWidth / 2;
+    const anchorY = isNegative
+      ? mark.y + mark.height + LABEL_OFFSET_Y
+      : mark.y - LABEL_OFFSET_Y - textHeight;
+
+    candidates.push({
+      text: valuePart,
+      anchorX,
+      anchorY,
+      width: textWidth,
+      height: textHeight,
+      priority: 'data',
+      style: {
+        fontFamily: 'system-ui, -apple-system, sans-serif',
+        fontSize: LABEL_FONT_SIZE,
+        fontWeight: LABEL_FONT_WEIGHT,
+        fill: mark.fill,
+        lineHeight: 1.2,
+        textAnchor: 'middle',
+        dominantBaseline: isNegative ? 'hanging' : 'auto',
+      },
+    });
+  }
+
+  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);
+}

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

@@ -0,0 +1,344 @@
+import type { LayoutStrategy, PointMark, Rect, RectMark } from '@opendata-ai/openchart-core';
+import { describe, expect, it } from 'vitest';
+import type { NormalizedChartSpec } from '../../../compiler/types';
+import { computeScales } from '../../../layout/scales';
+import { computeDotMarks } from '../compute';
+import { computeDotLabels } from '../labels';
+
+// ---------------------------------------------------------------------------
+// Shared fixtures
+// ---------------------------------------------------------------------------
+
+const chartArea: Rect = { x: 80, y: 20, width: 500, height: 300 };
+
+const fullStrategy: LayoutStrategy = {
+  labelMode: 'all',
+  legendPosition: 'right',
+  annotationPosition: 'inline',
+  axisLabelDensity: 'full',
+};
+
+function makeSimpleDotSpec(): NormalizedChartSpec {
+  return {
+    type: 'dot',
+    data: [
+      { country: 'USA', score: 85 },
+      { country: 'UK', score: 72 },
+      { country: 'Japan', score: 90 },
+      { country: 'France', score: 68 },
+    ],
+    encoding: {
+      x: { field: 'score', type: 'quantitative' },
+      y: { field: 'country', type: 'nominal' },
+    },
+    chrome: {},
+    annotations: [],
+    responsive: true,
+    theme: {},
+    darkMode: 'off',
+    labels: { density: 'auto', format: '' },
+  };
+}
+
+function makeColoredDotSpec(): NormalizedChartSpec {
+  return {
+    type: 'dot',
+    data: [
+      { item: 'Revenue', value: 120, status: 'good' },
+      { item: 'Costs', value: 80, status: 'neutral' },
+      { item: 'Profit', value: 40, status: 'good' },
+      { item: 'Debt', value: -10, status: 'bad' },
+    ],
+    encoding: {
+      x: { field: 'value', type: 'quantitative' },
+      y: { field: 'item', type: 'nominal' },
+      color: { field: 'status', type: 'nominal' },
+    },
+    chrome: {},
+    annotations: [],
+    responsive: true,
+    theme: {},
+    darkMode: 'off',
+    labels: { density: 'auto', format: '' },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// computeDotMarks tests
+// ---------------------------------------------------------------------------
+
+describe('computeDotMarks', () => {
+  describe('simple dot plot', () => {
+    it('produces PointMarks and RectMarks (stems)', () => {
+      const spec = makeSimpleDotSpec();
+      const scales = computeScales(spec, chartArea, spec.data);
+      const marks = computeDotMarks(spec, scales, chartArea, fullStrategy);
+
+      const points = marks.filter((m): m is PointMark => m.type === 'point');
+      const stems = marks.filter((m): m is RectMark => m.type === 'rect');
+
+      expect(points).toHaveLength(4);
+      expect(stems).toHaveLength(4);
+    });
+
+    it('dot positions reflect data values (higher score = further right)', () => {
+      const spec = makeSimpleDotSpec();
+      const scales = computeScales(spec, chartArea, spec.data);
+      const marks = computeDotMarks(spec, scales, chartArea, fullStrategy);
+
+      const points = marks.filter((m): m is PointMark => m.type === 'point');
+      const japan = points.find((m) => m.aria.label.includes('Japan'))!;
+      const france = points.find((m) => m.aria.label.includes('France'))!;
+
+      // Japan (90) should be further right than France (68)
+      expect(japan.cx).toBeGreaterThan(france.cx);
+    });
+
+    it('stems connect baseline to dot positions', () => {
+      const spec = makeSimpleDotSpec();
+      const scales = computeScales(spec, chartArea, spec.data);
+      const marks = computeDotMarks(spec, scales, chartArea, fullStrategy);
+
+      const stems = marks.filter((m): m is RectMark => m.type === 'rect');
+      for (const stem of stems) {
+        expect(stem.width).toBeGreaterThan(0);
+        expect(stem.height).toBe(2); // STEM_WIDTH
+      }
+    });
+
+    it('dots are vertically centered within their band', () => {
+      const spec = makeSimpleDotSpec();
+      const scales = computeScales(spec, chartArea, spec.data);
+      const marks = computeDotMarks(spec, scales, chartArea, fullStrategy);
+
+      const points = marks.filter((m): m is PointMark => m.type === 'point');
+      // All dots should be at different y positions (different categories)
+      const yPositions = points.map((p) => p.cy);
+      const uniqueY = new Set(yPositions);
+      expect(uniqueY.size).toBe(4);
+    });
+
+    it('dots have consistent radius', () => {
+      const spec = makeSimpleDotSpec();
+      const scales = computeScales(spec, chartArea, spec.data);
+      const marks = computeDotMarks(spec, scales, chartArea, fullStrategy);
+
+      const points = marks.filter((m): m is PointMark => m.type === 'point');
+      const radii = new Set(points.map((p) => p.r));
+      expect(radii.size).toBe(1);
+    });
+
+    it('each dot has an aria label with category and value', () => {
+      const spec = makeSimpleDotSpec();
+      const scales = computeScales(spec, chartArea, spec.data);
+      const marks = computeDotMarks(spec, scales, chartArea, fullStrategy);
+
+      const points = marks.filter((m): m is PointMark => m.type === 'point');
+      expect(points[0].aria.label).toContain('USA');
+      expect(points[0].aria.label).toContain('85');
+    });
+  });
+
+  describe('dumbbell (multi-series)', () => {
+    function makeDumbbellSpec(): NormalizedChartSpec {
+      return {
+        type: 'dot',
+        data: [
+          { country: 'USA', rate: 78, gender: 'Male' },
+          { country: 'USA', rate: 82, gender: 'Female' },
+          { country: 'Japan', rate: 85, gender: 'Male' },
+          { country: 'Japan', rate: 90, gender: 'Female' },
+          { country: 'Brazil', rate: 60, gender: 'Male' },
+          { country: 'Brazil', rate: 65, gender: 'Female' },
+        ],
+        encoding: {
+          x: { field: 'rate', type: 'quantitative' },
+          y: { field: 'country', type: 'nominal' },
+          color: { field: 'gender', type: 'nominal' },
+        },
+        chrome: {},
+        annotations: [],
+        responsive: true,
+        theme: {},
+        darkMode: 'off',
+        labels: { density: 'auto', format: '' },
+      };
+    }
+
+    it('renders connecting bars and dots for multi-series', () => {
+      const spec = makeDumbbellSpec();
+      const scales = computeScales(spec, chartArea, spec.data);
+      const marks = computeDotMarks(spec, scales, chartArea, fullStrategy);
+
+      const points = marks.filter((m): m is PointMark => m.type === 'point');
+      const bars = marks.filter((m): m is RectMark => m.type === 'rect');
+
+      // 6 data rows = 6 dots
+      expect(points).toHaveLength(6);
+      // 3 categories = 3 connecting bars
+      expect(bars).toHaveLength(3);
+    });
+
+    it('connecting bars span from min to max value per category', () => {
+      const spec = makeDumbbellSpec();
+      const scales = computeScales(spec, chartArea, spec.data);
+      const marks = computeDotMarks(spec, scales, chartArea, fullStrategy);
+
+      const bars = marks.filter((m): m is RectMark => m.type === 'rect');
+      for (const bar of bars) {
+        expect(bar.width).toBeGreaterThan(0);
+      }
+    });
+
+    it('connecting bars use stem color (gray)', () => {
+      const spec = makeDumbbellSpec();
+      const scales = computeScales(spec, chartArea, spec.data);
+      const marks = computeDotMarks(spec, scales, chartArea, fullStrategy);
+
+      const bars = marks.filter((m): m is RectMark => m.type === 'rect');
+      for (const bar of bars) {
+        expect(bar.fill).toBe('#cccccc');
+      }
+    });
+
+    it('dots within same category share the same cy position', () => {
+      const spec = makeDumbbellSpec();
+      const scales = computeScales(spec, chartArea, spec.data);
+      const marks = computeDotMarks(spec, scales, chartArea, fullStrategy);
+
+      const points = marks.filter((m): m is PointMark => m.type === 'point');
+      const usaDots = points.filter((m) => m.aria.label.includes('USA'));
+      expect(usaDots).toHaveLength(2);
+      expect(usaDots[0].cy).toBe(usaDots[1].cy);
+    });
+
+    it('dots for different series have different fill colors', () => {
+      const spec = makeDumbbellSpec();
+      const scales = computeScales(spec, chartArea, spec.data);
+      const marks = computeDotMarks(spec, scales, chartArea, fullStrategy);
+
+      const points = marks.filter((m): m is PointMark => m.type === 'point');
+      const maleDot = points.find((m) => m.aria.label.includes('Male'))!;
+      const femaleDot = points.find((m) => m.aria.label.includes('Female'))!;
+      expect(maleDot.fill).not.toBe(femaleDot.fill);
+    });
+
+    it('connecting bars render before dots (lower z-index)', () => {
+      const spec = makeDumbbellSpec();
+      const scales = computeScales(spec, chartArea, spec.data);
+      const marks = computeDotMarks(spec, scales, chartArea, fullStrategy);
+
+      // First mark should be a rect (connecting bar renders before dots)
+      expect(marks[0].type).toBe('rect');
+    });
+
+    it('aria labels include category and series name', () => {
+      const spec = makeDumbbellSpec();
+      const scales = computeScales(spec, chartArea, spec.data);
+      const marks = computeDotMarks(spec, scales, chartArea, fullStrategy);
+
+      const points = marks.filter((m): m is PointMark => m.type === 'point');
+      const usaMale = points.find(
+        (m) => m.aria.label.includes('USA') && m.aria.label.includes('Male'),
+      );
+      expect(usaMale).toBeDefined();
+      expect(usaMale!.aria.label).toContain('78');
+    });
+  });
+
+  describe('negative values', () => {
+    it('handles negative values (stem extends left of baseline)', () => {
+      const spec = makeColoredDotSpec();
+      const scales = computeScales(spec, chartArea, spec.data);
+      const marks = computeDotMarks(spec, scales, chartArea, fullStrategy);
+
+      const points = marks.filter((m): m is PointMark => m.type === 'point');
+      const debtDot = points.find((m) => m.data.item === 'Debt')!;
+      const revenueDot = points.find((m) => m.data.item === 'Revenue')!;
+
+      // Debt (-10) should be to the left of Revenue (120)
+      expect(debtDot.cx).toBeLessThan(revenueDot.cx);
+    });
+  });
+
+  describe('edge cases', () => {
+    it('returns empty array when no x encoding', () => {
+      const spec: NormalizedChartSpec = {
+        type: 'dot',
+        data: [{ country: 'USA', score: 85 }],
+        encoding: {
+          y: { field: 'country', type: 'nominal' },
+        },
+        chrome: {},
+        annotations: [],
+        responsive: true,
+        theme: {},
+        darkMode: 'off',
+        labels: { density: 'auto', format: '' },
+      };
+      const scales = computeScales(spec, chartArea, spec.data);
+      const marks = computeDotMarks(spec, scales, chartArea, fullStrategy);
+      expect(marks).toHaveLength(0);
+    });
+
+    it('returns empty array for empty data', () => {
+      const spec: NormalizedChartSpec = {
+        type: 'dot',
+        data: [],
+        encoding: {
+          x: { field: 'score', type: 'quantitative' },
+          y: { field: 'country', type: 'nominal' },
+        },
+        chrome: {},
+        annotations: [],
+        responsive: true,
+        theme: {},
+        darkMode: 'off',
+        labels: { density: 'auto', format: '' },
+      };
+      const scales = computeScales(spec, chartArea, spec.data);
+      const marks = computeDotMarks(spec, scales, chartArea, fullStrategy);
+      expect(marks).toHaveLength(0);
+    });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// computeDotLabels tests
+// ---------------------------------------------------------------------------
+
+describe('computeDotLabels', () => {
+  it('produces labels for each dot mark', () => {
+    const spec = makeSimpleDotSpec();
+    const scales = computeScales(spec, chartArea, spec.data);
+    const allMarks = computeDotMarks(spec, scales, chartArea, fullStrategy);
+    const points = allMarks.filter((m): m is PointMark => m.type === 'point');
+    const labels = computeDotLabels(points, chartArea);
+
+    expect(labels).toHaveLength(points.length);
+  });
+
+  it('labels are positioned to the right of dots', () => {
+    const spec = makeSimpleDotSpec();
+    const scales = computeScales(spec, chartArea, spec.data);
+    const allMarks = computeDotMarks(spec, scales, chartArea, fullStrategy);
+    const points = allMarks.filter((m): m is PointMark => m.type === 'point');
+    const labels = computeDotLabels(points, chartArea);
+
+    for (let i = 0; i < labels.length; i++) {
+      expect(labels[i].x).toBeGreaterThan(points[i].cx);
+    }
+  });
+
+  it('labels contain the numeric values', () => {
+    const spec = makeSimpleDotSpec();
+    const scales = computeScales(spec, chartArea, spec.data);
+    const allMarks = computeDotMarks(spec, scales, chartArea, fullStrategy);
+    const points = allMarks.filter((m): m is PointMark => m.type === 'point');
+    const labels = computeDotLabels(points, chartArea);
+
+    const texts = labels.map((l) => l.text);
+    expect(texts).toContain('85');
+    expect(texts).toContain('90');
+  });
+});