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

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

@@ -1,179 +0,0 @@
-import type { RectMark } from '@opendata-ai/openchart-core';
-import { buildD3Formatter } from '@opendata-ai/openchart-core';
-import { describe, expect, it } from 'vitest';
-import { computeColumnLabels } from '../labels';
-
-// ---------------------------------------------------------------------------
-// Fixtures
-// ---------------------------------------------------------------------------
-
-const chartArea = { x: 0, y: 0, width: 400, height: 300 };
-
-function makeMark(index: number, value: number): RectMark {
-  const height = Math.abs(value) * 5;
-  const y = value >= 0 ? 300 - height : 300;
-  return {
-    type: 'rect',
-    x: index * 80,
-    y,
-    width: 60,
-    height,
-    fill: '#4e79a7',
-    data: { category: `Cat${index}`, value },
-    aria: { label: `Cat${index}: ${value}` },
-  };
-}
-
-const marks: RectMark[] = [
-  makeMark(0, 10),
-  makeMark(1, 20),
-  makeMark(2, 30),
-  makeMark(3, 40),
-  makeMark(4, 50),
-];
-
-// ---------------------------------------------------------------------------
-// Tests
-// ---------------------------------------------------------------------------
-
-describe('computeColumnLabels density modes', () => {
-  it('density "auto" runs collision detection and produces labels', () => {
-    const labels = computeColumnLabels(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 = computeColumnLabels(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 = computeColumnLabels(marks, chartArea, 'none');
-    expect(labels).toHaveLength(0);
-  });
-
-  it('density "endpoints" returns only first and last labels', () => {
-    const labels = computeColumnLabels(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 = computeColumnLabels([marks[0]], chartArea, 'endpoints');
-    expect(labels).toHaveLength(1);
-    expect(labels[0].text).toBe('10');
-  });
-
-  it('default density is "auto"', () => {
-    const withAuto = computeColumnLabels(marks, chartArea, 'auto');
-    const withDefault = computeColumnLabels(marks, chartArea);
-    expect(withDefault.length).toBe(withAuto.length);
-  });
-});
-
-describe('computeColumnLabels positioning', () => {
-  it('places positive value labels above the column', () => {
-    const labels = computeColumnLabels([makeMark(0, 20)], chartArea, 'all');
-    expect(labels).toHaveLength(1);
-    const mark = makeMark(0, 20);
-    // Label y should be above the column top
-    expect(labels[0].y).toBeLessThan(mark.y);
-  });
-
-  it('places negative value labels below the column', () => {
-    const negativeMark = makeMark(0, -15);
-    const labels = computeColumnLabels([negativeMark], chartArea, 'all');
-    expect(labels).toHaveLength(1);
-    // Label y should be below the column bottom
-    expect(labels[0].y).toBeGreaterThan(negativeMark.y + negativeMark.height);
-  });
-
-  it('centers labels horizontally on the column', () => {
-    const labels = computeColumnLabels([makeMark(0, 20)], chartArea, 'all');
-    const mark = makeMark(0, 20);
-    const markCenter = mark.x + mark.width / 2;
-    expect(labels[0].x).toBe(markCenter);
-  });
-
-  it('applies labelFormat to numeric values', () => {
-    const labels = computeColumnLabels(
-      [makeMark(0, 1234)],
-      chartArea,
-      'all',
-      buildD3Formatter(',.0f'),
-    );
-    expect(labels[0].text).toBe('1,234');
-  });
-});
-
-describe('computeColumnLabels stacked segments', () => {
-  /** One segment of a stacked column, positioned by its top edge. */
-  function makeStackedMark(y: number, height: number, fill: string, value: number): RectMark {
-    return {
-      type: 'rect',
-      x: 0,
-      y,
-      width: 60,
-      height,
-      fill,
-      stackGroup: 'Cat0',
-      data: { category: 'Cat0', value },
-      aria: { label: `Cat0: ${value}` },
-    };
-  }
-
-  it('centers the label inside its own segment, not above it', () => {
-    // Above a stacked segment's top edge is the next segment up, not the
-    // background, so the label must stay within its own band.
-    const mark = makeStackedMark(100, 80, '#0e7490', 33);
-    const labels = computeColumnLabels([mark], chartArea, 'all');
-
-    expect(labels).toHaveLength(1);
-    expect(labels[0].y).toBeGreaterThan(mark.y);
-    expect(labels[0].y).toBeLessThan(mark.y + mark.height);
-  });
-
-  it('picks a fill that contrasts with its own segment', () => {
-    // A dark segment takes white text; a light segment takes near-black. The
-    // old code tinted the text with the segment's own series color, which put
-    // colored text on a colored fill.
-    const dark = computeColumnLabels([makeStackedMark(100, 80, '#0e7490', 33)], chartArea, 'all');
-    const light = computeColumnLabels([makeStackedMark(100, 80, '#e2e8f0', 33)], chartArea, 'all');
-
-    expect(dark[0].style.fill).toBe('#ffffff');
-    expect(light[0].style.fill).toBe('#111111');
-  });
-
-  it('hides the label when the segment is too short to hold it', () => {
-    // A ~4% segment (Nuclear in the energy-mix demo) can't fit a 10px label
-    // without spilling into its neighbours.
-    const labels = computeColumnLabels([makeStackedMark(100, 6, '#0e7490', 4)], chartArea, 'all');
-
-    expect(labels).toHaveLength(1);
-    expect(labels[0].visible).toBe(false);
-  });
-
-  it('an explicit labels.color still wins over the contrast pick', () => {
-    const labels = computeColumnLabels(
-      [makeStackedMark(100, 80, '#0e7490', 33)],
-      chartArea,
-      'all',
-      undefined,
-      undefined,
-      undefined,
-      '#ff00ff',
-    );
-
-    expect(labels[0].style.fill).toBe('#ff00ff');
-  });
-
-  it('leaves unstacked columns labeling above the bar', () => {
-    const mark = makeMark(0, 20);
-    const labels = computeColumnLabels([mark], chartArea, 'all');
-
-    expect(labels[0].y).toBeLessThan(mark.y);
-  });
-});

package/src/charts/column/compute.ts

@@ -1,493 +0,0 @@
-/**
- * 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 either stacked (cumulative heights) or grouped
- * (side-by-side) based on the `stack` property of the quantitative channel.
- *
- * Shares conceptual logic with bar chart but axes are swapped:
- * x-axis is categorical (band scale), y-axis is quantitative.
- */
-
-import type {
-  ConditionalValueDef,
-  DataRow,
-  Encoding,
-  GradientDef,
-  LayoutStrategy,
-  MarkAria,
-  Rect,
-  RectMark,
-} from '@opendata-ai/openchart-core';
-import { isGradientDef } 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 { isConditionalValueDef, resolveConditionalValue } from '../../transforms/conditional';
-import { formatLabelValue } from '../_shared/format-label-value';
-import { getColor, getSequentialColor, groupByField } from '../utils';
-
-// ---------------------------------------------------------------------------
-// Constants
-// ---------------------------------------------------------------------------
-
-const MIN_COLUMN_HEIGHT = 1;
-
-// ---------------------------------------------------------------------------
-// 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();
-  // Baseline = pixel y where the column's bottom edge anchors. When the
-  // y-domain includes zero (the common case), this is yScale(0). Sparkline
-  // mode tightens the domain to [min, max] (zero: false) so yScale(0) lands
-  // outside the chart area; in that case we anchor to the bottom of the
-  // y-range instead, otherwise every bar would render with the same height.
-  const yDomain = yScale.domain() as [number, number];
-  const yIncludesZero = yDomain[0] <= 0 && yDomain[1] >= 0;
-  const baseline = yIncludesZero ? yScale(0) : yScale(yDomain[0]);
-  const colorEnc = encoding.color && 'field' in encoding.color ? encoding.color : undefined;
-  const conditionalColor =
-    encoding.color && isConditionalValueDef(encoding.color)
-      ? (encoding.color as ConditionalValueDef)
-      : undefined;
-  const colorField = colorEnc?.field;
-
-  const isSequentialColor = colorEnc?.type === 'quantitative';
-
-  let marks: RectMark[];
-
-  // 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) {
-      // stack: undefined/true/'zero'/'normalize'/'center' -> stacked (default); null/false -> grouped
-      const stackEnabled = yChannel.stack !== null && yChannel.stack !== false;
-
-      if (!stackEnabled) {
-        marks = computeGroupedColumns(
-          spec.data,
-          xChannel.field,
-          yChannel.field,
-          colorField,
-          xScale,
-          yScale,
-          bandwidth,
-          baseline,
-          scales,
-        );
-      } else {
-        const stackMode =
-          yChannel.stack === 'normalize'
-            ? 'normalize'
-            : yChannel.stack === 'center'
-              ? 'center'
-              : 'zero';
-
-        marks = computeStackedColumns(
-          spec.data,
-          xChannel.field,
-          yChannel.field,
-          colorField,
-          xScale,
-          yScale,
-          bandwidth,
-          baseline,
-          scales,
-          stackMode,
-        );
-      }
-    } else {
-      // Single row per category: render like simple columns but with color from scale
-      marks = computeColoredColumns(
-        spec.data,
-        xChannel.field,
-        yChannel.field,
-        colorField,
-        xScale,
-        yScale,
-        bandwidth,
-        baseline,
-        scales,
-      );
-    }
-  } else {
-    marks = computeSimpleColumns(
-      spec.data,
-      xChannel.field,
-      yChannel.field,
-      xScale,
-      yScale,
-      bandwidth,
-      baseline,
-      scales,
-      isSequentialColor,
-      conditionalColor,
-    );
-  }
-
-  // Stamp identity keys for data-update transitions
-  const categoryField = xChannel.field;
-  stampColumnKeys(marks, categoryField, colorField);
-
-  return applyMarkDefOverrides(marks, spec, bandwidth);
-}
-
-/** Stamp stable identity keys on column marks for data-update transitions. */
-function stampColumnKeys(marks: RectMark[], categoryField: string, colorField?: string): void {
-  const rawKeys = marks.map((m) => {
-    const series = colorField ? String(m.data[colorField] ?? '') : '';
-    const cat = serializeKeyValue(m.data[categoryField]);
-    return `${series}|${cat}`;
-  });
-  const keys = dedupeKeys(rawKeys);
-  for (let i = 0; i < marks.length; i++) {
-    marks[i].key = keys[i];
-  }
-}
-
-/** 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,
-  conditionalColor?: ConditionalValueDef,
-): 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;
-
-    let color: string | GradientDef;
-    if (conditionalColor) {
-      const resolved = resolveConditionalValue(row, conditionalColor);
-      if (resolved != null) {
-        color = isGradientDef(resolved) ? resolved : String(resolved);
-      } else {
-        color = getColor(scales, '__default__');
-      }
-    } else if (sequentialColor) {
-      color = getSequentialColor(scales, value);
-    } else {
-      color = 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}: ${formatLabelValue(value)}`,
-    };
-
-    marks.push({
-      type: 'rect',
-      x: bandX,
-      y,
-      width: bandwidth,
-      height: columnHeight,
-      fill: color,
-      cornerRadius: 2,
-      data: row as Record<string, unknown>,
-      aria,
-      orient: 'vertical',
-    });
-  }
-
-  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}: ${formatLabelValue(value)}`,
-    };
-
-    marks.push({
-      type: 'rect',
-      x: bandX,
-      y,
-      width: bandwidth,
-      height: columnHeight,
-      fill: color,
-      cornerRadius: 2,
-      data: row as Record<string, unknown>,
-      aria,
-      orient: 'vertical',
-    });
-  }
-
-  return marks;
-}
-
-/** Compute grouped (dodged) vertical columns -- side-by-side within each category band. */
-function computeGroupedColumns(
-  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);
-
-  // Build a stable group order from first appearance in data (Map for O(1) lookup)
-  const groupIndexMap = new Map<string, number>();
-  for (const row of data) {
-    const key = String(row[colorField] ?? '');
-    if (!groupIndexMap.has(key)) {
-      groupIndexMap.set(key, groupIndexMap.size);
-    }
-  }
-  const groupCount = groupIndexMap.size;
-  if (groupCount === 0) return marks;
-
-  // Subdivide the band width by group count with a small gap
-  const gap = Math.min(1, bandwidth * 0.05);
-  const subBandWidth = Math.max(
-    (bandwidth - gap * (groupCount - 1)) / groupCount,
-    MIN_COLUMN_HEIGHT,
-  );
-
-  for (const [category, rows] of categoryGroups) {
-    const bandX = xScale(category);
-    if (bandX === undefined) continue;
-
-    for (const row of rows) {
-      const groupKey = String(row[colorField] ?? '');
-      const value = Number(row[valueField] ?? 0);
-      if (!Number.isFinite(value)) continue;
-
-      const groupIndex = groupIndexMap.get(groupKey) ?? 0;
-      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 subX = bandX + groupIndex * (subBandWidth + gap);
-
-      const aria: MarkAria = {
-        label: `${category}, ${groupKey}: ${formatLabelValue(value)}`,
-      };
-
-      marks.push({
-        type: 'rect',
-        x: subX,
-        y,
-        width: subBandWidth,
-        height: columnHeight,
-        fill: color,
-        cornerRadius: 2,
-        data: row as Record<string, unknown>,
-        aria,
-        orient: 'vertical',
-      });
-    }
-  }
-
-  return marks;
-}
-
-/** Compute stacked vertical columns with support for zero/normalize/center modes. */
-function computeStackedColumns(
-  data: DataRow[],
-  categoryField: string,
-  valueField: string,
-  colorField: string,
-  xScale: ScaleBand<string>,
-  yScale: ScaleLinear<number, number>,
-  bandwidth: number,
-  _baseline: number,
-  scales: ResolvedScales,
-  stackMode: 'zero' | 'normalize' | 'center' = 'zero',
-): RectMark[] {
-  const marks: RectMark[] = [];
-  const categoryGroups = groupByField(data, categoryField);
-
-  for (const [category, rows] of categoryGroups) {
-    const bandX = xScale(category);
-    if (bandX === undefined) continue;
-
-    // Compute category total for normalize/center modes
-    let categoryTotal = 0;
-    for (const row of rows) {
-      const v = Number(row[valueField] ?? 0);
-      if (Number.isFinite(v) && v > 0) categoryTotal += v;
-    }
-
-    // For center mode, offset so the stack is centered around zero
-    let cumulativeValue = stackMode === 'center' ? -categoryTotal / 2 : 0;
-
-    for (const row of rows) {
-      const groupKey = String(row[colorField] ?? '');
-      const rawValue = 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(rawValue) || rawValue <= 0) continue;
-
-      // For normalize mode, scale the value to a fraction of the total
-      const value =
-        stackMode === 'normalize' && categoryTotal > 0 ? rawValue / categoryTotal : rawValue;
-
-      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}: ${formatLabelValue(rawValue)}`,
-      };
-
-      marks.push({
-        type: 'rect',
-        x: bandX,
-        y: Math.min(yTop, yBottom),
-        width: bandwidth,
-        height: columnHeight,
-        fill: color,
-        cornerRadius: 0,
-        data: row as Record<string, unknown>,
-        aria,
-        orient: 'vertical',
-        stackGroup: category,
-      });
-
-      cumulativeValue += value;
-    }
-  }
-
-  return marks;
-}
-
-function applyMarkDefOverrides(
-  marks: RectMark[],
-  spec: NormalizedChartSpec,
-  bandwidth: number,
-): RectMark[] {
-  const { markDef } = spec;
-  const fixedSize = markDef.size;
-  const crSpec = markDef.cornerRadius;
-
-  if (fixedSize == null && crSpec == null) return marks;
-
-  // Identify the topmost segment per stackGroup (smallest `y` since SVG
-  // grows downward). Only that segment receives the corner rounding so
-  // the seams between stacked segments stay square and flush.
-  const topPerStack = new Map<string, RectMark>();
-  for (const mark of marks) {
-    if (mark.stackGroup === undefined) continue;
-    const current = topPerStack.get(mark.stackGroup);
-    if (!current || mark.y < current.y) {
-      topPerStack.set(mark.stackGroup, mark);
-    }
-  }
-
-  for (const mark of marks) {
-    if (fixedSize != null && mark.stackGroup === undefined) {
-      const barWidth = Math.min(fixedSize, bandwidth);
-      const offset = (bandwidth - barWidth) / 2;
-      mark.x = mark.x + offset;
-      mark.width = barWidth;
-    }
-    const effectiveWidth = mark.width;
-    const isStacked = mark.stackGroup !== undefined;
-    const isStackTop = isStacked && topPerStack.get(mark.stackGroup!) === mark;
-
-    // Stacked segments below the top stay square. Stack top rounds only its
-    // top corners; non-stacked bars round all four.
-    if (isStacked && !isStackTop) continue;
-
-    if (crSpec === 'pill') {
-      mark.cornerRadius = effectiveWidth / 2;
-    } else if (typeof crSpec === 'number') {
-      mark.cornerRadius = crSpec;
-    } else {
-      continue;
-    }
-
-    if (isStackTop) {
-      mark.cornerRadiusSides = { tl: true, tr: true, br: false, bl: false };
-    }
-  }
-
-  return marks;
-}