@opendata-ai/openchart-engine 1.2.0

package/src/charts/bar/labels.ts

@@ -0,0 +1,132 @@
+/**
+ * Bar chart label computation.
+ *
+ * Produces value labels for horizontal bars, positioned inside the bar
+ * if the bar is wide enough, or outside (to the right) otherwise.
+ *
+ * Respects the spec's label density setting:
+ * - 'all': show every label, skip collision detection
+ * - 'auto': existing behavior (collision detection)
+ * - 'endpoints': first and last bars 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 = 11;
+const LABEL_FONT_WEIGHT = 600;
+const LABEL_PADDING = 6;
+const MIN_WIDTH_FOR_INSIDE_LABEL = 40;
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute value labels for bar marks.
+ *
+ * For each bar, the value from the data is formatted and placed either
+ * inside the bar (right-aligned) if the bar is wide enough, or just
+ * outside the bar's right edge.
+ */
+export function computeBarLabels(
+  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 textWidth = estimateTextWidth(valuePart, LABEL_FONT_SIZE, LABEL_FONT_WEIGHT);
+    const textHeight = LABEL_FONT_SIZE * 1.2;
+
+    // Detect stacked bars: cornerRadius 0 indicates stacked segment
+    const isStacked = mark.cornerRadius === 0;
+
+    // Determine if label goes inside or outside the bar
+    const isInside = mark.width >= MIN_WIDTH_FOR_INSIDE_LABEL;
+
+    let anchorX: number;
+    let fill: string;
+    let textAnchor: 'start' | 'end' | 'middle';
+
+    if (isStacked && isInside) {
+      // Stacked: centered within segment
+      anchorX = mark.x + mark.width / 2;
+      fill = '#ffffff';
+      textAnchor = 'middle';
+    } else if (isInside) {
+      // Simple: right-aligned within bar
+      anchorX = mark.x + mark.width - LABEL_PADDING;
+      fill = '#ffffff';
+      textAnchor = 'end';
+    } else {
+      // Outside: just past the bar's right edge
+      anchorX = mark.x + mark.width + LABEL_PADDING;
+      fill = mark.fill;
+      textAnchor = 'start';
+    }
+
+    // anchorY = bar vertical center. With dominant-baseline: central,
+    // SVG places the text center at this y coordinate.
+    const anchorY = mark.y + mark.height / 2;
+
+    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,
+        lineHeight: 1.2,
+        textAnchor,
+        dominantBaseline: 'central',
+      },
+    });
+  }
+
+  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/column/__tests__/compute.test.ts

@@ -0,0 +1,277 @@
+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 { computeColumnMarks } from '../compute';
+import { computeColumnLabels } from '../labels';
+
+// ---------------------------------------------------------------------------
+// Shared fixtures
+// ---------------------------------------------------------------------------
+
+const chartArea: Rect = { x: 50, y: 20, width: 500, height: 300 };
+
+const fullStrategy: LayoutStrategy = {
+  labelMode: 'all',
+  legendPosition: 'right',
+  annotationPosition: 'inline',
+  axisLabelDensity: 'full',
+};
+
+function makeSimpleColumnSpec(): NormalizedChartSpec {
+  return {
+    type: 'column',
+    data: [
+      { month: 'Jan', sales: 120 },
+      { month: 'Feb', sales: 80 },
+      { month: 'Mar', sales: 150 },
+      { month: 'Apr', sales: 200 },
+    ],
+    encoding: {
+      x: { field: 'month', type: 'nominal' },
+      y: { field: 'sales', type: 'quantitative' },
+    },
+    chrome: {},
+    annotations: [],
+    responsive: true,
+    theme: {},
+    darkMode: 'off',
+    labels: { density: 'auto', format: '' },
+  };
+}
+
+function makeGroupedColumnSpec(): NormalizedChartSpec {
+  return {
+    type: 'column',
+    data: [
+      { month: 'Jan', sales: 120, region: 'North' },
+      { month: 'Jan', sales: 80, region: 'South' },
+      { month: 'Feb', sales: 90, region: 'North' },
+      { month: 'Feb', sales: 110, region: 'South' },
+      { month: 'Mar', sales: 150, region: 'North' },
+      { month: 'Mar', sales: 130, region: 'South' },
+    ],
+    encoding: {
+      x: { field: 'month', type: 'nominal' },
+      y: { field: 'sales', type: 'quantitative' },
+      color: { field: 'region', type: 'nominal' },
+    },
+    chrome: {},
+    annotations: [],
+    responsive: true,
+    theme: {},
+    darkMode: 'off',
+    labels: { density: 'auto', format: '' },
+  };
+}
+
+function makeNegativeColumnSpec(): NormalizedChartSpec {
+  return {
+    type: 'column',
+    data: [
+      { quarter: 'Q1', growth: 5 },
+      { quarter: 'Q2', growth: -3 },
+      { quarter: 'Q3', growth: 8 },
+      { quarter: 'Q4', growth: -1 },
+    ],
+    encoding: {
+      x: { field: 'quarter', type: 'nominal' },
+      y: { field: 'growth', type: 'quantitative' },
+    },
+    chrome: {},
+    annotations: [],
+    responsive: true,
+    theme: {},
+    darkMode: 'off',
+    labels: { density: 'auto', format: '' },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// computeColumnMarks tests
+// ---------------------------------------------------------------------------
+
+describe('computeColumnMarks', () => {
+  describe('simple columns', () => {
+    it('produces one RectMark per data row', () => {
+      const spec = makeSimpleColumnSpec();
+      const scales = computeScales(spec, chartArea, spec.data);
+      const marks = computeColumnMarks(spec, scales, chartArea, fullStrategy);
+
+      expect(marks).toHaveLength(4);
+      expect(marks.every((m) => m.type === 'rect')).toBe(true);
+    });
+
+    it('columns have positive width and height', () => {
+      const spec = makeSimpleColumnSpec();
+      const scales = computeScales(spec, chartArea, spec.data);
+      const marks = computeColumnMarks(spec, scales, chartArea, fullStrategy);
+
+      for (const mark of marks) {
+        expect(mark.width).toBeGreaterThan(0);
+        expect(mark.height).toBeGreaterThan(0);
+      }
+    });
+
+    it('taller columns correspond to larger values', () => {
+      const spec = makeSimpleColumnSpec();
+      const scales = computeScales(spec, chartArea, spec.data);
+      const marks = computeColumnMarks(spec, scales, chartArea, fullStrategy);
+
+      // Apr (200) should be taller than Feb (80)
+      const apr = marks.find((m) => m.aria.label.includes('Apr'))!;
+      const feb = marks.find((m) => m.aria.label.includes('Feb'))!;
+      expect(apr.height).toBeGreaterThan(feb.height);
+    });
+
+    it('higher values have lower y positions (SVG coordinates)', () => {
+      const spec = makeSimpleColumnSpec();
+      const scales = computeScales(spec, chartArea, spec.data);
+      const marks = computeColumnMarks(spec, scales, chartArea, fullStrategy);
+
+      const apr = marks.find((m) => m.aria.label.includes('Apr'))!;
+      const feb = marks.find((m) => m.aria.label.includes('Feb'))!;
+      // Apr (200) should start higher (lower y) than Feb (80)
+      expect(apr.y).toBeLessThan(feb.y);
+    });
+
+    it('each column has an aria label with category and value', () => {
+      const spec = makeSimpleColumnSpec();
+      const scales = computeScales(spec, chartArea, spec.data);
+      const marks = computeColumnMarks(spec, scales, chartArea, fullStrategy);
+
+      expect(marks[0].aria.label).toContain('Jan');
+      expect(marks[0].aria.label).toContain('120');
+    });
+  });
+
+  describe('stacked columns', () => {
+    it('produces marks for all data rows', () => {
+      const spec = makeGroupedColumnSpec();
+      const scales = computeScales(spec, chartArea, spec.data);
+      const marks = computeColumnMarks(spec, scales, chartArea, fullStrategy);
+
+      // 3 categories * 2 groups = 6
+      expect(marks).toHaveLength(6);
+    });
+
+    it('stacked segments within a category have different colors', () => {
+      const spec = makeGroupedColumnSpec();
+      const scales = computeScales(spec, chartArea, spec.data);
+      const marks = computeColumnMarks(spec, scales, chartArea, fullStrategy);
+
+      const janMarks = marks.filter((m) => m.aria.label.includes('Jan'));
+      expect(janMarks).toHaveLength(2);
+      expect(janMarks[0].fill).not.toBe(janMarks[1].fill);
+    });
+
+    it('stacked columns within a category share the same x position', () => {
+      const spec = makeGroupedColumnSpec();
+      const scales = computeScales(spec, chartArea, spec.data);
+      const marks = computeColumnMarks(spec, scales, chartArea, fullStrategy);
+
+      const janNorth = marks.find(
+        (m) => m.aria.label.includes('Jan') && m.aria.label.includes('North'),
+      )!;
+      const janSouth = marks.find(
+        (m) => m.aria.label.includes('Jan') && m.aria.label.includes('South'),
+      )!;
+
+      // Stacked columns share the same x position
+      expect(janNorth.x).toBe(janSouth.x);
+      // But have different y positions (stacked vertically)
+      expect(janNorth.y).not.toBe(janSouth.y);
+    });
+  });
+
+  describe('negative values', () => {
+    it('negative columns extend downward from baseline', () => {
+      const spec = makeNegativeColumnSpec();
+      const scales = computeScales(spec, chartArea, spec.data);
+      const marks = computeColumnMarks(spec, scales, chartArea, fullStrategy);
+
+      const q2 = marks.find((m) => m.aria.label.includes('Q2'))!;
+      const q1 = marks.find((m) => m.aria.label.includes('Q1'))!;
+
+      // Negative value column should start at a higher y (lower on page = baseline)
+      expect(q2.y).toBeGreaterThan(q1.y);
+    });
+
+    it('all columns have positive height', () => {
+      const spec = makeNegativeColumnSpec();
+      const scales = computeScales(spec, chartArea, spec.data);
+      const marks = computeColumnMarks(spec, scales, chartArea, fullStrategy);
+
+      for (const mark of marks) {
+        expect(mark.height).toBeGreaterThan(0);
+      }
+    });
+  });
+
+  describe('edge cases', () => {
+    it('returns empty array when no y encoding', () => {
+      const spec: NormalizedChartSpec = {
+        type: 'column',
+        data: [{ month: 'Jan', sales: 100 }],
+        encoding: {
+          x: { field: 'month', type: 'nominal' },
+        },
+        chrome: {},
+        annotations: [],
+        responsive: true,
+        theme: {},
+        darkMode: 'off',
+        labels: { density: 'auto', format: '' },
+      };
+      const scales = computeScales(spec, chartArea, spec.data);
+      const marks = computeColumnMarks(spec, scales, chartArea, fullStrategy);
+      expect(marks).toHaveLength(0);
+    });
+
+    it('returns empty array for empty data', () => {
+      const spec: NormalizedChartSpec = {
+        type: 'column',
+        data: [],
+        encoding: {
+          x: { field: 'month', type: 'nominal' },
+          y: { field: 'sales', type: 'quantitative' },
+        },
+        chrome: {},
+        annotations: [],
+        responsive: true,
+        theme: {},
+        darkMode: 'off',
+        labels: { density: 'auto', format: '' },
+      };
+      const scales = computeScales(spec, chartArea, spec.data);
+      const marks = computeColumnMarks(spec, scales, chartArea, fullStrategy);
+      expect(marks).toHaveLength(0);
+    });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// computeColumnLabels tests
+// ---------------------------------------------------------------------------
+
+describe('computeColumnLabels', () => {
+  it('produces one label per column mark', () => {
+    const spec = makeSimpleColumnSpec();
+    const scales = computeScales(spec, chartArea, spec.data);
+    const marks = computeColumnMarks(spec, scales, chartArea, fullStrategy);
+    const labels = computeColumnLabels(marks, chartArea);
+
+    expect(labels).toHaveLength(marks.length);
+  });
+
+  it('labels contain the value text', () => {
+    const spec = makeSimpleColumnSpec();
+    const scales = computeScales(spec, chartArea, spec.data);
+    const marks = computeColumnMarks(spec, scales, chartArea, fullStrategy);
+    const labels = computeColumnLabels(marks, chartArea);
+
+    const texts = labels.map((l) => l.text);
+    expect(texts).toContain('120');
+    expect(texts).toContain('200');
+  });
+});

package/src/charts/column/compute.ts

@@ -0,0 +1,282 @@
+/**
+ * Column chart (vertical bars) mark computation.
+ *
+ * Takes a normalized chart spec with resolved scales and produces
+ * RectMark[] for rendering vertical columns. When a color encoding
+ * is present, columns are stacked (cumulative heights per category).
+ *
+ * Shares conceptual logic with bar chart but axes are swapped:
+ * x-axis is categorical (band scale), y-axis is quantitative.
+ */
+
+import type {
+  DataRow,
+  Encoding,
+  LayoutStrategy,
+  MarkAria,
+  Rect,
+  RectMark,
+} from '@opendata-ai/openchart-core';
+import { abbreviateNumber, formatNumber } from '@opendata-ai/openchart-core';
+import type { ScaleBand, ScaleLinear } from 'd3-scale';
+
+import type { NormalizedChartSpec } from '../../compiler/types';
+import type { ResolvedScales } from '../../layout/scales';
+import { getColor, getSequentialColor, groupByField } from '../utils';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const MIN_COLUMN_HEIGHT = 1;
+
+/** Format a column value for display (abbreviate large numbers). */
+function formatColumnValue(value: number): string {
+  if (Math.abs(value) >= 1000) return abbreviateNumber(value);
+  return formatNumber(value);
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute vertical column marks from a normalized chart spec.
+ *
+ * X axis uses a band scale for categories. Y axis uses a linear scale
+ * for values. When a color encoding is present, columns within each
+ * category are stacked (cumulative heights).
+ */
+export function computeColumnMarks(
+  spec: NormalizedChartSpec,
+  scales: ResolvedScales,
+  _chartArea: Rect,
+  _strategy: LayoutStrategy,
+): 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 ScaleBand<string>;
+  const yScale = scales.y.scale as ScaleLinear<number, number>;
+
+  // Band scale should provide bandwidth
+  if (typeof xScale.bandwidth !== 'function') {
+    return [];
+  }
+
+  const bandwidth = xScale.bandwidth();
+  const baseline = yScale(0);
+  const colorField = encoding.color?.field;
+
+  const isSequentialColor = encoding.color?.type === 'quantitative';
+
+  // Color encoding present: decide between colored simple columns vs stacked
+  if (colorField && !isSequentialColor) {
+    // Check if any category has multiple rows (actual stacking needed)
+    const categoryGroups = groupByField(spec.data, xChannel.field);
+    const needsStacking = Array.from(categoryGroups.values()).some((rows) => rows.length > 1);
+
+    if (needsStacking) {
+      return computeStackedColumns(
+        spec.data,
+        xChannel.field,
+        yChannel.field,
+        colorField,
+        xScale,
+        yScale,
+        bandwidth,
+        baseline,
+        scales,
+      );
+    }
+
+    // Single row per category: render like simple columns but with color from scale
+    return computeColoredColumns(
+      spec.data,
+      xChannel.field,
+      yChannel.field,
+      colorField,
+      xScale,
+      yScale,
+      bandwidth,
+      baseline,
+      scales,
+    );
+  }
+
+  return computeSimpleColumns(
+    spec.data,
+    xChannel.field,
+    yChannel.field,
+    xScale,
+    yScale,
+    bandwidth,
+    baseline,
+    scales,
+    isSequentialColor,
+  );
+}
+
+/** Compute simple (non-grouped) vertical columns. */
+function computeSimpleColumns(
+  data: DataRow[],
+  categoryField: string,
+  valueField: string,
+  xScale: ScaleBand<string>,
+  yScale: ScaleLinear<number, number>,
+  bandwidth: number,
+  baseline: number,
+  scales: ResolvedScales,
+  sequentialColor = false,
+): RectMark[] {
+  const marks: RectMark[] = [];
+
+  for (const row of data) {
+    const category = String(row[categoryField] ?? '');
+    const value = Number(row[valueField] ?? 0);
+    if (!Number.isFinite(value)) continue;
+
+    const bandX = xScale(category);
+    if (bandX === undefined) continue;
+
+    const color = sequentialColor
+      ? getSequentialColor(scales, value)
+      : getColor(scales, '__default__');
+    const yPos = yScale(value);
+    const columnHeight = Math.max(Math.abs(baseline - yPos), MIN_COLUMN_HEIGHT);
+
+    // For positive values, column goes upward from baseline.
+    // For negative values, column goes downward from baseline.
+    const y = value >= 0 ? yPos : baseline;
+
+    const aria: MarkAria = {
+      label: `${category}: ${formatColumnValue(value)}`,
+    };
+
+    marks.push({
+      type: 'rect',
+      x: bandX,
+      y,
+      width: bandwidth,
+      height: columnHeight,
+      fill: color,
+      cornerRadius: 2,
+      data: row as Record<string, unknown>,
+      aria,
+    });
+  }
+
+  return marks;
+}
+
+/** Compute colored (non-stacked) vertical columns. Used when color encoding
+ *  is present but each category has only one row (e.g., diverging charts). */
+function computeColoredColumns(
+  data: DataRow[],
+  categoryField: string,
+  valueField: string,
+  colorField: string,
+  xScale: ScaleBand<string>,
+  yScale: ScaleLinear<number, number>,
+  bandwidth: number,
+  baseline: number,
+  scales: ResolvedScales,
+): RectMark[] {
+  const marks: RectMark[] = [];
+
+  for (const row of data) {
+    const category = String(row[categoryField] ?? '');
+    const value = Number(row[valueField] ?? 0);
+    if (!Number.isFinite(value)) continue;
+
+    const bandX = xScale(category);
+    if (bandX === undefined) continue;
+
+    const groupKey = String(row[colorField] ?? '');
+    const color = getColor(scales, groupKey);
+    const yPos = yScale(value);
+    const columnHeight = Math.max(Math.abs(baseline - yPos), MIN_COLUMN_HEIGHT);
+
+    const y = value >= 0 ? yPos : baseline;
+
+    const aria: MarkAria = {
+      label: `${category}, ${groupKey}: ${formatColumnValue(value)}`,
+    };
+
+    marks.push({
+      type: 'rect',
+      x: bandX,
+      y,
+      width: bandwidth,
+      height: columnHeight,
+      fill: color,
+      cornerRadius: 2,
+      data: row as Record<string, unknown>,
+      aria,
+    });
+  }
+
+  return marks;
+}
+
+/** Compute stacked vertical columns. */
+function computeStackedColumns(
+  data: DataRow[],
+  categoryField: string,
+  valueField: string,
+  colorField: string,
+  xScale: ScaleBand<string>,
+  yScale: ScaleLinear<number, number>,
+  bandwidth: number,
+  _baseline: number,
+  scales: ResolvedScales,
+): RectMark[] {
+  const marks: RectMark[] = [];
+  const categoryGroups = groupByField(data, categoryField);
+
+  for (const [category, rows] of categoryGroups) {
+    const bandX = xScale(category);
+    if (bandX === undefined) continue;
+
+    let cumulativeValue = 0;
+
+    for (const row of rows) {
+      const groupKey = String(row[colorField] ?? '');
+      const value = Number(row[valueField] ?? 0);
+      // Stacking only applies to positive values; negative/zero rows are skipped
+      // since cumulative stacking doesn't make visual sense for mixed signs.
+      if (!Number.isFinite(value) || value <= 0) continue;
+
+      const color = getColor(scales, groupKey);
+
+      const yTop = yScale(cumulativeValue + value);
+      const yBottom = yScale(cumulativeValue);
+      const columnHeight = Math.max(Math.abs(yBottom - yTop), MIN_COLUMN_HEIGHT);
+
+      const aria: MarkAria = {
+        label: `${category}, ${groupKey}: ${formatColumnValue(value)}`,
+      };
+
+      marks.push({
+        type: 'rect',
+        x: bandX,
+        y: yTop,
+        width: bandwidth,
+        height: columnHeight,
+        fill: color,
+        cornerRadius: 0,
+        data: row as Record<string, unknown>,
+        aria,
+      });
+
+      cumulativeValue += value;
+    }
+  }
+
+  return marks;
+}