@opendata-ai/openchart-engine 1.2.0

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

@@ -0,0 +1,276 @@
+import type { LayoutStrategy, Rect } from '@opendata-ai/openchart-core';
+import { describe, expect, it } from 'vitest';
+import type { NormalizedChartSpec } from '../../../compiler/types';
+import { computeScales } from '../../../layout/scales';
+import { computePieMarks } from '../compute';
+import { computePieLabels } from '../labels';
+
+// ---------------------------------------------------------------------------
+// Shared fixtures
+// ---------------------------------------------------------------------------
+
+const chartArea: Rect = { x: 50, y: 20, width: 400, height: 400 };
+
+const fullStrategy: LayoutStrategy = {
+  labelMode: 'all',
+  legendPosition: 'right',
+  annotationPosition: 'inline',
+  axisLabelDensity: 'full',
+};
+
+function makeBasicPieSpec(): NormalizedChartSpec {
+  return {
+    type: 'pie',
+    data: [
+      { category: 'A', value: 40 },
+      { category: 'B', value: 30 },
+      { category: 'C', value: 20 },
+      { category: 'D', value: 10 },
+    ],
+    encoding: {
+      y: { field: 'value', type: 'quantitative' },
+      color: { field: 'category', type: 'nominal' },
+    },
+    chrome: {},
+    annotations: [],
+    responsive: true,
+    theme: {},
+    darkMode: 'off',
+    labels: { density: 'auto', format: '' },
+  };
+}
+
+function makeSmallSlicePieSpec(): NormalizedChartSpec {
+  return {
+    type: 'pie',
+    data: [
+      { category: 'Big', value: 90 },
+      { category: 'Medium', value: 7 },
+      { category: 'Tiny1', value: 1 },
+      { category: 'Tiny2', value: 1 },
+      { category: 'Tiny3', value: 1 },
+    ],
+    encoding: {
+      y: { field: 'value', type: 'quantitative' },
+      color: { field: 'category', type: 'nominal' },
+    },
+    chrome: {},
+    annotations: [],
+    responsive: true,
+    theme: {},
+    darkMode: 'off',
+    labels: { density: 'auto', format: '' },
+  };
+}
+
+function makeDonutSpec(): NormalizedChartSpec {
+  return {
+    type: 'donut',
+    data: [
+      { segment: 'Desktop', users: 55 },
+      { segment: 'Mobile', users: 35 },
+      { segment: 'Tablet', users: 10 },
+    ],
+    encoding: {
+      y: { field: 'users', type: 'quantitative' },
+      color: { field: 'segment', type: 'nominal' },
+    },
+    chrome: {},
+    annotations: [],
+    responsive: true,
+    theme: {},
+    darkMode: 'off',
+    labels: { density: 'auto', format: '' },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// computePieMarks tests
+// ---------------------------------------------------------------------------
+
+describe('computePieMarks', () => {
+  describe('basic pie', () => {
+    it('produces ArcMarks for each category', () => {
+      const spec = makeBasicPieSpec();
+      const scales = computeScales(spec, chartArea, spec.data);
+      const marks = computePieMarks(spec, scales, chartArea, fullStrategy, false);
+
+      expect(marks).toHaveLength(4);
+      expect(marks.every((m) => m.type === 'arc')).toBe(true);
+    });
+
+    it('arc paths are non-empty strings', () => {
+      const spec = makeBasicPieSpec();
+      const scales = computeScales(spec, chartArea, spec.data);
+      const marks = computePieMarks(spec, scales, chartArea, fullStrategy, false);
+
+      for (const mark of marks) {
+        expect(mark.path).toBeTruthy();
+        expect(mark.path.length).toBeGreaterThan(0);
+      }
+    });
+
+    it('arcs are sorted largest first', () => {
+      const spec = makeBasicPieSpec();
+      const scales = computeScales(spec, chartArea, spec.data);
+      const marks = computePieMarks(spec, scales, chartArea, fullStrategy, false);
+
+      // First arc should be largest (A: 40)
+      const firstArc = marks[0];
+      expect(firstArc.aria.label).toContain('A');
+
+      // Arc angles should be in descending order (largest angle first)
+      const angles = marks.map((m) => m.endAngle - m.startAngle);
+      for (let i = 0; i < angles.length - 1; i++) {
+        expect(angles[i]).toBeGreaterThanOrEqual(angles[i + 1] - 0.02); // pad angle tolerance
+      }
+    });
+
+    it('pie has zero inner radius', () => {
+      const spec = makeBasicPieSpec();
+      const scales = computeScales(spec, chartArea, spec.data);
+      const marks = computePieMarks(spec, scales, chartArea, fullStrategy, false);
+
+      for (const mark of marks) {
+        expect(mark.innerRadius).toBe(0);
+      }
+    });
+
+    it('arcs have white stroke for separation', () => {
+      const spec = makeBasicPieSpec();
+      const scales = computeScales(spec, chartArea, spec.data);
+      const marks = computePieMarks(spec, scales, chartArea, fullStrategy, false);
+
+      for (const mark of marks) {
+        expect(mark.stroke).toBe('#ffffff');
+        expect(mark.strokeWidth).toBeGreaterThan(0);
+      }
+    });
+
+    it('each arc has aria label with value and percentage', () => {
+      const spec = makeBasicPieSpec();
+      const scales = computeScales(spec, chartArea, spec.data);
+      const marks = computePieMarks(spec, scales, chartArea, fullStrategy, false);
+
+      expect(marks[0].aria.label).toContain('40');
+      expect(marks[0].aria.label).toContain('%');
+    });
+
+    it('each arc has a centroid point for label positioning', () => {
+      const spec = makeBasicPieSpec();
+      const scales = computeScales(spec, chartArea, spec.data);
+      const marks = computePieMarks(spec, scales, chartArea, fullStrategy, false);
+
+      for (const mark of marks) {
+        expect(mark.centroid).toBeDefined();
+        expect(typeof mark.centroid.x).toBe('number');
+        expect(typeof mark.centroid.y).toBe('number');
+      }
+    });
+  });
+
+  describe('small-slice grouping', () => {
+    it('groups slices below threshold into "Other"', () => {
+      const spec = makeSmallSlicePieSpec();
+      const scales = computeScales(spec, chartArea, spec.data);
+      const marks = computePieMarks(spec, scales, chartArea, fullStrategy, false);
+
+      // Tiny1, Tiny2, Tiny3 are each 1% (< 3% threshold) -> grouped into "Other"
+      const labels = marks.map((m) => m.aria.label);
+      const otherSlice = labels.find((l) => l.includes('Other'));
+      expect(otherSlice).toBeTruthy();
+
+      // Should be 3 marks: Big, Medium, Other
+      expect(marks).toHaveLength(3);
+    });
+  });
+
+  describe('donut variant', () => {
+    it('donut has positive inner radius', () => {
+      const spec = makeDonutSpec();
+      const scales = computeScales(spec, chartArea, spec.data);
+      const marks = computePieMarks(spec, scales, chartArea, fullStrategy, true);
+
+      for (const mark of marks) {
+        expect(mark.innerRadius).toBeGreaterThan(0);
+      }
+    });
+
+    it('donut inner radius is about 60% of outer radius', () => {
+      const spec = makeDonutSpec();
+      const scales = computeScales(spec, chartArea, spec.data);
+      const marks = computePieMarks(spec, scales, chartArea, fullStrategy, true);
+
+      const ratio = marks[0].innerRadius / marks[0].outerRadius;
+      expect(ratio).toBeCloseTo(0.6, 1);
+    });
+  });
+
+  describe('edge cases', () => {
+    it('returns empty array when no value encoding', () => {
+      const spec: NormalizedChartSpec = {
+        type: 'pie',
+        data: [{ category: 'A' }],
+        encoding: {
+          color: { field: 'category', type: 'nominal' },
+        },
+        chrome: {},
+        annotations: [],
+        responsive: true,
+        theme: {},
+        darkMode: 'off',
+        labels: { density: 'auto', format: '' },
+      };
+      const scales = computeScales(spec, chartArea, spec.data);
+      const marks = computePieMarks(spec, scales, chartArea, fullStrategy, false);
+      expect(marks).toHaveLength(0);
+    });
+
+    it('returns empty array for empty data', () => {
+      const spec: NormalizedChartSpec = {
+        type: 'pie',
+        data: [],
+        encoding: {
+          y: { field: 'value', type: 'quantitative' },
+          color: { field: 'category', type: 'nominal' },
+        },
+        chrome: {},
+        annotations: [],
+        responsive: true,
+        theme: {},
+        darkMode: 'off',
+        labels: { density: 'auto', format: '' },
+      };
+      const scales = computeScales(spec, chartArea, spec.data);
+      const marks = computePieMarks(spec, scales, chartArea, fullStrategy, false);
+      expect(marks).toHaveLength(0);
+    });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// computePieLabels tests
+// ---------------------------------------------------------------------------
+
+describe('computePieLabels', () => {
+  it('produces labels for each arc mark', () => {
+    const spec = makeBasicPieSpec();
+    const scales = computeScales(spec, chartArea, spec.data);
+    const marks = computePieMarks(spec, scales, chartArea, fullStrategy, false);
+    const labels = computePieLabels(marks, chartArea);
+
+    expect(labels).toHaveLength(marks.length);
+  });
+
+  it('labels have connector lines to centroids', () => {
+    const spec = makeBasicPieSpec();
+    const scales = computeScales(spec, chartArea, spec.data);
+    const marks = computePieMarks(spec, scales, chartArea, fullStrategy, false);
+    const labels = computePieLabels(marks, chartArea);
+
+    const visibleLabels = labels.filter((l) => l.visible);
+    for (const label of visibleLabels) {
+      expect(label.connector).toBeDefined();
+    }
+  });
+});

package/src/charts/pie/compute.ts

@@ -0,0 +1,234 @@
+/**
+ * Pie / donut chart mark computation.
+ *
+ * Uses d3.pie() for angle calculation and d3.arc() for SVG path
+ * generation. Supports sorting by value (largest first), small-slice
+ * grouping into "Other", and donut variant with inner radius.
+ */
+
+import type {
+  ArcMark,
+  DataRow,
+  Encoding,
+  LayoutStrategy,
+  MarkAria,
+  Rect,
+} from '@opendata-ai/openchart-core';
+import type { PieArcDatum } from 'd3-shape';
+import { arc as d3Arc, pie as d3Pie } from 'd3-shape';
+
+import type { NormalizedChartSpec } from '../../compiler/types';
+import type { ResolvedScales } from '../../layout/scales';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/** Slices smaller than this fraction are grouped into "Other". */
+const SMALL_SLICE_THRESHOLD = 0.03;
+
+/** Default color palette when no color scale is available. */
+const DEFAULT_PALETTE = [
+  '#1b7fa3',
+  '#c44e52',
+  '#6a9f58',
+  '#d47215',
+  '#507e79',
+  '#9a6a8d',
+  '#c4636b',
+  '#9c755f',
+  '#a88f22',
+  '#858078',
+];
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+interface SliceData {
+  label: string;
+  value: number;
+  originalRow: DataRow;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Group small slices (< threshold) into an "Other" category. */
+function groupSmallSlices(slices: SliceData[], threshold: number): SliceData[] {
+  const total = slices.reduce((sum, s) => sum + s.value, 0);
+  if (total === 0) return slices;
+
+  const big: SliceData[] = [];
+  let otherValue = 0;
+
+  for (const slice of slices) {
+    if (slice.value / total < threshold) {
+      otherValue += slice.value;
+    } else {
+      big.push(slice);
+    }
+  }
+
+  if (otherValue > 0) {
+    big.push({
+      label: 'Other',
+      value: otherValue,
+      originalRow: { label: 'Other', value: otherValue },
+    });
+  }
+
+  return big;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute pie or donut arc marks from a normalized chart spec.
+ *
+ * Extracts category and value from the encoding channels. Categories
+ * come from the color field, values from the quantitative y (or x) field.
+ * Slices are sorted largest first. Small slices are grouped into "Other".
+ *
+ * @param isDonut - When true, creates a donut with inner radius at 60% of outer.
+ */
+export function computePieMarks(
+  spec: NormalizedChartSpec,
+  scales: ResolvedScales,
+  chartArea: Rect,
+  _strategy: LayoutStrategy,
+  isDonut = false,
+): ArcMark[] {
+  const encoding = spec.encoding as Encoding;
+
+  // For pie/donut charts, we need a value field (typically y or x) and
+  // a category field (typically color). The value field provides the slice sizes.
+  const valueChannel = encoding.y ?? encoding.x;
+  const categoryField = encoding.color?.field;
+
+  if (!valueChannel) return [];
+
+  // Build slices from data
+  let slices: SliceData[] = [];
+
+  if (categoryField) {
+    // Aggregate by category
+    const categoryTotals = new Map<string, number>();
+    const categoryRows = new Map<string, DataRow>();
+
+    for (const row of spec.data) {
+      const cat = String(row[categoryField] ?? '');
+      const val = Number(row[valueChannel.field] ?? 0);
+      if (!Number.isFinite(val) || val < 0) continue;
+
+      categoryTotals.set(cat, (categoryTotals.get(cat) ?? 0) + val);
+      if (!categoryRows.has(cat)) {
+        categoryRows.set(cat, row);
+      }
+    }
+
+    for (const [label, value] of categoryTotals) {
+      slices.push({
+        label,
+        value,
+        originalRow: categoryRows.get(label) ?? {
+          [categoryField]: label,
+          [valueChannel.field]: value,
+        },
+      });
+    }
+  } else {
+    // Each data row is a slice. Use a label field if present, or index.
+    for (let i = 0; i < spec.data.length; i++) {
+      const row = spec.data[i];
+      const val = Number(row[valueChannel.field] ?? 0);
+      if (!Number.isFinite(val) || val < 0) continue;
+
+      // Try common label fields
+      const label = String(row.label ?? row.name ?? row.category ?? `Slice ${i + 1}`);
+
+      slices.push({ label, value: val, originalRow: row });
+    }
+  }
+
+  if (slices.length === 0) return [];
+
+  // Sort by value descending (largest first)
+  slices.sort((a, b) => b.value - a.value);
+
+  // Group small slices into "Other"
+  slices = groupSmallSlices(slices, SMALL_SLICE_THRESHOLD);
+
+  // Compute pie layout
+  const pieGenerator = d3Pie<SliceData>()
+    .value((d) => d.value)
+    .sort(null) // Already sorted
+    .padAngle(0.01);
+
+  const arcs = pieGenerator(slices);
+
+  // Compute arc dimensions
+  const centerX = chartArea.x + chartArea.width / 2;
+  const centerY = chartArea.y + chartArea.height / 2;
+  const outerRadius = (Math.min(chartArea.width, chartArea.height) / 2) * 0.85;
+  const innerRadius = isDonut ? outerRadius * 0.6 : 0;
+
+  const arcGenerator = d3Arc<PieArcDatum<SliceData>>()
+    .innerRadius(innerRadius)
+    .outerRadius(outerRadius);
+
+  // Build arc marks
+  const marks: ArcMark[] = [];
+  const center = { x: centerX, y: centerY };
+  const total = slices.reduce((sum, s) => sum + s.value, 0);
+
+  for (let i = 0; i < arcs.length; i++) {
+    const arcDatum = arcs[i];
+    const slice = arcDatum.data;
+
+    // Get color from scale or default palette
+    let color: string;
+    if (scales.color && categoryField) {
+      const colorScale = scales.color.scale as (v: string) => string;
+      color = colorScale(slice.label);
+    } else {
+      color = DEFAULT_PALETTE[i % DEFAULT_PALETTE.length];
+    }
+
+    // Generate SVG path (relative to 0,0; renderer wraps in translate)
+    const path = arcGenerator(arcDatum) ?? '';
+
+    // Compute centroid (for label positioning), offset to chart center
+    const centroidResult = arcGenerator.centroid(arcDatum);
+
+    const percentage = total > 0 ? ((slice.value / total) * 100).toFixed(1) : '0';
+
+    const aria: MarkAria = {
+      label: `${slice.label}: ${slice.value} (${percentage}%)`,
+    };
+
+    marks.push({
+      type: 'arc',
+      path,
+      centroid: {
+        x: centroidResult[0] + centerX,
+        y: centroidResult[1] + centerY,
+      },
+      center,
+      innerRadius,
+      outerRadius,
+      startAngle: arcDatum.startAngle,
+      endAngle: arcDatum.endAngle,
+      fill: color,
+      stroke: '#ffffff',
+      strokeWidth: 2,
+      data: slice.originalRow as Record<string, unknown>,
+      aria,
+    });
+  }
+
+  return marks;
+}

package/src/charts/pie/index.ts

@@ -0,0 +1,49 @@
+/**
+ * Pie and donut chart module.
+ *
+ * Exports pie and donut chart renderers and computation functions.
+ */
+
+import type { Mark } from '@opendata-ai/openchart-core';
+import type { ChartRenderer } from '../registry';
+import { computePieMarks } from './compute';
+import { computePieLabels } from './labels';
+
+// ---------------------------------------------------------------------------
+// Pie chart renderer
+// ---------------------------------------------------------------------------
+
+export const pieRenderer: ChartRenderer = (spec, scales, chartArea, strategy, theme) => {
+  const marks = computePieMarks(spec, scales, chartArea, strategy, false);
+
+  // Compute and attach labels (respects spec.labels.density)
+  const labels = computePieLabels(marks, chartArea, spec.labels.density, theme.colors.text);
+  for (let i = 0; i < marks.length && i < labels.length; i++) {
+    marks[i].label = labels[i];
+  }
+
+  return marks as Mark[];
+};
+
+// ---------------------------------------------------------------------------
+// Donut chart renderer
+// ---------------------------------------------------------------------------
+
+export const donutRenderer: ChartRenderer = (spec, scales, chartArea, strategy, theme) => {
+  const marks = computePieMarks(spec, scales, chartArea, strategy, true);
+
+  // Compute and attach labels (respects spec.labels.density)
+  const labels = computePieLabels(marks, chartArea, spec.labels.density, theme.colors.text);
+  for (let i = 0; i < marks.length && i < labels.length; i++) {
+    marks[i].label = labels[i];
+  }
+
+  return marks as Mark[];
+};
+
+// ---------------------------------------------------------------------------
+// Public exports
+// ---------------------------------------------------------------------------
+
+export { computePieMarks } from './compute';
+export { computePieLabels } from './labels';

package/src/charts/pie/labels.ts

@@ -0,0 +1,142 @@
+/**
+ * Pie/donut chart label computation.
+ *
+ * Produces leader-line labels positioned outside each arc slice.
+ * Labels are placed at the midpoint of each arc's angle, extended
+ * outward from the centroid. Collision detection resolves overlaps.
+ *
+ * Respects the spec's label density setting:
+ * - 'all': show every label, skip collision detection
+ * - 'auto': existing behavior (collision detection)
+ * - 'endpoints': first and last slices only
+ * - 'none': return empty array
+ */
+
+import type {
+  ArcMark,
+  LabelCandidate,
+  LabelDensity,
+  Rect,
+  ResolvedLabel,
+} from '@opendata-ai/openchart-core';
+import { estimateTextWidth, resolveCollisions } from '@opendata-ai/openchart-core';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const LABEL_FONT_SIZE = 10;
+const LABEL_FONT_WEIGHT = 500;
+const LEADER_LINE_OFFSET = 12;
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute leader-line labels for pie/donut arc marks.
+ *
+ * Each label is positioned outward from the arc centroid with a connector
+ * line from the centroid to the label. Labels go through collision
+ * detection to avoid overlap.
+ */
+export function computePieLabels(
+  marks: ArcMark[],
+  _chartArea: Rect,
+  density: LabelDensity = 'auto',
+  _textFill = '#333333',
+): ResolvedLabel[] {
+  if (marks.length === 0) return [];
+
+  // 'none': no labels at all
+  if (density === 'none') return [];
+
+  // Get the pie center from the first mark's center property
+  const centerX = marks[0].center.x;
+  const centerY = marks[0].center.y;
+
+  // Filter marks for 'endpoints' density
+  const targetMarks =
+    density === 'endpoints' && marks.length > 1 ? [marks[0], marks[marks.length - 1]] : marks;
+
+  const candidates: LabelCandidate[] = [];
+  const targetMarkIndices: number[] = [];
+
+  for (let mi = 0; mi < targetMarks.length; mi++) {
+    const mark = targetMarks[mi];
+    // Extract the label text (category name) from the aria label.
+    // Format is "Category: value (percent%)". Split on the first colon
+    // to handle category names that might contain colons.
+    const ariaLabel = mark.aria.label;
+    const firstColon = ariaLabel.indexOf(':');
+    const labelText = firstColon >= 0 ? ariaLabel.slice(0, firstColon).trim() : '';
+    if (!labelText) continue;
+
+    const textWidth = estimateTextWidth(labelText, LABEL_FONT_SIZE, LABEL_FONT_WEIGHT);
+    const textHeight = LABEL_FONT_SIZE * 1.2;
+
+    // Position label outward from centroid
+    const midAngle = (mark.startAngle + mark.endAngle) / 2;
+    const labelRadius = mark.outerRadius + LEADER_LINE_OFFSET;
+
+    const labelX = centerX + Math.sin(midAngle) * labelRadius;
+    const labelY = centerY - Math.cos(midAngle) * labelRadius;
+
+    // Determine text anchor based on which side of the pie the label is on
+    const isRight = Math.sin(midAngle) > 0;
+
+    candidates.push({
+      text: labelText,
+      anchorX: isRight ? labelX : labelX - textWidth,
+      anchorY: labelY - 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: _textFill,
+        lineHeight: 1.2,
+        textAnchor: isRight ? 'start' : 'end',
+        dominantBaseline: 'central',
+      },
+    });
+
+    targetMarkIndices.push(mi);
+  }
+
+  if (candidates.length === 0) return [];
+
+  // 'all': skip collision detection, mark everything visible
+  let resolved: ResolvedLabel[];
+  if (density === 'all') {
+    resolved = candidates.map((c) => ({
+      text: c.text,
+      x: c.anchorX,
+      y: c.anchorY,
+      style: c.style,
+      visible: true,
+    }));
+  } else {
+    // Run collision detection
+    resolved = resolveCollisions(candidates);
+  }
+
+  // Add connector lines from centroid to label
+  for (let i = 0; i < resolved.length && i < targetMarks.length; i++) {
+    const label = resolved[i];
+    const mark = targetMarks[i];
+
+    if (label.visible) {
+      label.connector = {
+        from: { x: label.x, y: label.y },
+        to: { x: mark.centroid.x, y: mark.centroid.y },
+        stroke: _textFill,
+        style: 'straight',
+      };
+    }
+  }
+
+  return resolved;
+}