@opendata-ai/openchart-engine 7.11.0 → 8.0.0-rc.10

package/src/charts/range/compute.ts

@@ -0,0 +1,273 @@
+/**
+ * Range chart mark computation (dumbbell / arrow / range bar).
+ *
+ * A band scale on the nominal axis and two quantitative positions per row
+ * (x + x2 horizontal, or y + y2 vertical). Three styles via markDef.style:
+ * - 'dumbbell' (default): connector rule + a dot at each end. The start dot
+ *   is muted, the end dot carries the accent color.
+ * - 'arrow': shaft rule + chevron arrowhead at the x2/y2 end, built from the
+ *   shared computeArrowheadPoints geometry.
+ * - 'bar': plain floating RectMark spanning start to end.
+ *
+ * Coloring precedence for the accent (connector/shaft/bar + end dot):
+ * field-based encoding.color > markDef.colorByDirection (positive/negative
+ * semantic tokens) > scales.defaultColor (markDef.fill or first palette color).
+ */
+
+import type {
+  Encoding,
+  LayoutStrategy,
+  Mark,
+  MarkAria,
+  Rect,
+  ResolvedTheme,
+} from '@opendata-ai/openchart-core';
+import { getRepresentativeColor } from '@opendata-ai/openchart-core';
+import type { ScaleBand, ScaleLinear } from 'd3-scale';
+
+import { computeArrowheadPoints } from '../../annotations/geometry';
+import { dedupeKeys, serializeKeyValue } from '../../compiler/keys';
+import type { NormalizedChartSpec } from '../../compiler/types';
+import type { ResolvedScales } from '../../layout/scales';
+import { getColor } from '../utils';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const DOT_RADIUS = 6;
+const CONNECTOR_WIDTH = 2;
+const CONNECTOR_COLOR = '#cccccc';
+const ARROW_STROKE_WIDTH = 2;
+const ARROWHEAD_LENGTH = 8;
+const ARROWHEAD_HALF_WIDTH = 4;
+
+/** Range mark style variants. */
+export type RangeStyle = 'dumbbell' | 'arrow' | 'bar';
+
+// ---------------------------------------------------------------------------
+// Orientation helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve the range orientation from resolved scales.
+ * Horizontal (nominal y, the common editorial form) when y is a band scale;
+ * vertical when x is a band scale.
+ */
+export function resolveRangeOrientation(scales: ResolvedScales): 'horizontal' | 'vertical' | null {
+  if (
+    scales.y?.type === 'band' &&
+    typeof (scales.y.scale as ScaleBand<string>).bandwidth === 'function'
+  ) {
+    return 'horizontal';
+  }
+  if (
+    scales.x?.type === 'band' &&
+    typeof (scales.x.scale as ScaleBand<string>).bandwidth === 'function'
+  ) {
+    return 'vertical';
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute range marks from a normalized chart spec.
+ *
+ * Emission order per data row is stable and load-bearing for the label pass:
+ * connector/shaft/bar first (so dots layer on top), then the start dot, then
+ * the end dot (dumbbell style only).
+ */
+export function computeRangeMarks(
+  spec: NormalizedChartSpec,
+  scales: ResolvedScales,
+  _chartArea: Rect,
+  _strategy: LayoutStrategy,
+  theme: ResolvedTheme,
+): Mark[] {
+  const encoding = spec.encoding as Encoding;
+  const orientation = resolveRangeOrientation(scales);
+  if (!orientation || !scales.x || !scales.y) return [];
+
+  const horizontal = orientation === 'horizontal';
+  const catChannel = horizontal ? encoding.y : encoding.x;
+  const startChannel = horizontal ? encoding.x : encoding.y;
+  const endChannel = horizontal ? encoding.x2 : encoding.y2;
+  if (!catChannel || !startChannel || !endChannel) return [];
+
+  const bandScale = (horizontal ? scales.y.scale : scales.x.scale) as ScaleBand<string>;
+  const valueScale = (horizontal ? scales.x.scale : scales.y.scale) as ScaleLinear<number, number>;
+  const bandwidth = bandScale.bandwidth();
+
+  const style: RangeStyle = spec.markDef.style ?? 'dumbbell';
+  const colorEnc = encoding.color && 'field' in encoding.color ? encoding.color : undefined;
+  const colorByDirection = spec.markDef.colorByDirection === true && !colorEnc;
+
+  // Stable identity keys per category row (deduped for repeated categories).
+  const catKeys = dedupeKeys(spec.data.map((row) => serializeKeyValue(row[catChannel.field])));
+
+  const marks: Mark[] = [];
+
+  for (let i = 0; i < spec.data.length; i++) {
+    const row = spec.data[i];
+    const category = String(row[catChannel.field] ?? '');
+    const bandPos = bandScale(category);
+    if (bandPos === undefined) continue;
+
+    const startRaw = row[startChannel.field];
+    const endRaw = row[endChannel.field];
+    if (startRaw == null || endRaw == null) continue;
+    const startVal = Number(startRaw);
+    const endVal = Number(endRaw);
+    if (!Number.isFinite(startVal) || !Number.isFinite(endVal)) continue;
+
+    const center = bandPos + bandwidth / 2;
+    const pStart = valueScale(startVal);
+    const pEnd = valueScale(endVal);
+    const delta = endVal - startVal;
+    const catKey = catKeys[i];
+
+    // Accent: field color > direction color > default (markDef.fill / palette).
+    const accent = colorEnc
+      ? getColor(scales, String(row[colorEnc.field] ?? ''))
+      : colorByDirection
+        ? delta > 0
+          ? theme.colors.positive
+          : delta < 0
+            ? theme.colors.negative
+            : theme.colors.axis
+        : getColor(scales, '__default__');
+    const accentStroke = getRepresentativeColor(accent);
+
+    const spanAria: MarkAria = {
+      label: `${category}: ${startVal} to ${endVal}`,
+    };
+
+    // Pixel endpoints in x/y space
+    const x1 = horizontal ? pStart : center;
+    const y1 = horizontal ? center : pStart;
+    const x2 = horizontal ? pEnd : center;
+    const y2 = horizontal ? center : pEnd;
+    const spanLength = Math.abs(pEnd - pStart);
+
+    if (style === 'bar') {
+      marks.push({
+        type: 'rect',
+        x: horizontal ? Math.min(pStart, pEnd) : bandPos,
+        y: horizontal ? bandPos : Math.min(pStart, pEnd),
+        width: horizontal ? spanLength : bandwidth,
+        height: horizontal ? bandwidth : spanLength,
+        fill: accent,
+        data: row as Record<string, unknown>,
+        aria: spanAria,
+        key: catKey,
+        orient: horizontal ? 'horizontal' : 'vertical',
+      });
+      continue;
+    }
+
+    if (style === 'arrow') {
+      if (spanLength > 0) {
+        marks.push({
+          type: 'rule',
+          x1,
+          y1,
+          x2,
+          y2,
+          stroke: accentStroke,
+          strokeWidth: ARROW_STROKE_WIDTH,
+          data: row as Record<string, unknown>,
+          aria: spanAria,
+          key: `${catKey}|range`,
+        });
+
+        // Chevron arrowhead at the end value, from the shared geometry helper.
+        const head = computeArrowheadPoints(
+          x2,
+          y2,
+          x2 - x1,
+          y2 - y1,
+          ARROWHEAD_LENGTH,
+          ARROWHEAD_HALF_WIDTH,
+        );
+        const headAria: MarkAria = { label: spanAria.label, decorative: true };
+        marks.push(
+          {
+            type: 'rule',
+            x1: head.baseLeft.x,
+            y1: head.baseLeft.y,
+            x2: head.tip.x,
+            y2: head.tip.y,
+            stroke: accentStroke,
+            strokeWidth: ARROW_STROKE_WIDTH,
+            data: row as Record<string, unknown>,
+            aria: headAria,
+            key: `${catKey}|head-left`,
+          },
+          {
+            type: 'rule',
+            x1: head.baseRight.x,
+            y1: head.baseRight.y,
+            x2: head.tip.x,
+            y2: head.tip.y,
+            stroke: accentStroke,
+            strokeWidth: ARROW_STROKE_WIDTH,
+            data: row as Record<string, unknown>,
+            aria: headAria,
+            key: `${catKey}|head-right`,
+          },
+        );
+      }
+      continue;
+    }
+
+    // Dumbbell (default): connector + muted start dot + accent end dot.
+    if (spanLength > 0) {
+      const connectorColor = colorEnc || colorByDirection ? accentStroke : CONNECTOR_COLOR;
+      marks.push({
+        type: 'rule',
+        x1,
+        y1,
+        x2,
+        y2,
+        stroke: connectorColor,
+        strokeWidth: CONNECTOR_WIDTH,
+        data: row as Record<string, unknown>,
+        aria: spanAria,
+        key: `${catKey}|range`,
+      });
+    }
+
+    marks.push(
+      {
+        type: 'point',
+        cx: x1,
+        cy: y1,
+        r: DOT_RADIUS,
+        fill: theme.colors.axis,
+        stroke: '#ffffff',
+        strokeWidth: 2,
+        data: row as Record<string, unknown>,
+        aria: { label: `${category}, start: ${startVal}` },
+        key: `${catKey}|start`,
+      },
+      {
+        type: 'point',
+        cx: x2,
+        cy: y2,
+        r: DOT_RADIUS,
+        fill: accent,
+        stroke: '#ffffff',
+        strokeWidth: 2,
+        data: row as Record<string, unknown>,
+        aria: { label: `${category}, end: ${endVal}` },
+        key: `${catKey}|end`,
+      },
+    );
+  }
+
+  return marks;
+}

package/src/charts/range/index.ts

@@ -0,0 +1,82 @@
+/**
+ * Range chart module (dumbbell / arrow / range bar).
+ *
+ * Exports the range chart renderer and computation functions.
+ */
+
+import type { PointMark } from '@opendata-ai/openchart-core';
+import { resolveFieldFormatter } from '../../format/field-format';
+import type { ChartRenderer } from '../registry';
+import { computeRangeMarks, resolveRangeOrientation } from './compute';
+import { computeRangeLabels, type RangeDotPair } from './labels';
+
+// ---------------------------------------------------------------------------
+// Range chart renderer
+// ---------------------------------------------------------------------------
+
+/**
+ * Range chart renderer.
+ *
+ * Produces connector/shaft/bar spans plus dot pairs (dumbbell style).
+ * Both-end value labels are attached to the dumbbell dot marks; arrow and
+ * bar styles have no dot anchors and render without value labels.
+ */
+export const rangeRenderer: ChartRenderer = (spec, scales, chartArea, strategy, theme) => {
+  const marks = computeRangeMarks(spec, scales, chartArea, strategy, theme);
+
+  const style = spec.markDef.style ?? 'dumbbell';
+  if (style !== 'dumbbell') return marks;
+
+  // Dumbbell dots are emitted in (start, end) order per row; pair them up
+  // for the both-end label pass.
+  const dots = marks.filter((m): m is PointMark => m.type === 'point');
+  const pairs: RangeDotPair[] = [];
+  for (let i = 0; i + 1 < dots.length; i += 2) {
+    pairs.push({ start: dots[i], end: dots[i + 1] });
+  }
+
+  const orientation = resolveRangeOrientation(scales);
+  const horizontal = orientation !== 'vertical';
+  const encoding = spec.encoding;
+  const startChannel = horizontal ? encoding.x : encoding.y;
+  const endChannel = horizontal ? encoding.x2 : encoding.y2;
+
+  const startField = startChannel && 'field' in startChannel ? startChannel.field : undefined;
+  const endField = endChannel && 'field' in endChannel ? endChannel.field : undefined;
+  const startValues = startField ? spec.data.map((r) => r[startField]) : [];
+  const endValues = endField ? spec.data.map((r) => r[endField]) : [];
+  const labelFormatter = resolveFieldFormatter({
+    surfaceFormat: spec.labels.format,
+    channelFormat: startChannel && 'format' in startChannel ? startChannel.format : undefined,
+    values: [...startValues, ...endValues],
+  });
+  const labels = computeRangeLabels(
+    pairs,
+    horizontal,
+    spec.labels.density,
+    spec.labels.prefix,
+    labelFormatter,
+    startField,
+    endField,
+  );
+
+  // Attach labels back onto their dots via the index carried through the
+  // label pass (pairIndex * 2 = start dot, pairIndex * 2 + 1 = end dot).
+  for (const label of labels) {
+    if (label.index === undefined) continue;
+    const pair = pairs[Math.floor(label.index / 2)];
+    if (!pair) continue;
+    const dot = label.index % 2 === 0 ? pair.start : pair.end;
+    dot.label = label;
+  }
+
+  return marks;
+};
+
+// ---------------------------------------------------------------------------
+// Public exports
+// ---------------------------------------------------------------------------
+
+export { computeRangeMarks, resolveRangeOrientation } from './compute';
+export type { RangeDotPair } from './labels';
+export { computeRangeLabels } from './labels';

package/src/charts/range/labels.ts

@@ -0,0 +1,169 @@
+/**
+ * Range chart label computation (dumbbell style).
+ *
+ * Produces value labels at both ends of each dumbbell: outside the range span
+ * so labels never sit on the connector. Horizontal ranges label left of the
+ * lower-value dot and right of the higher-value dot; vertical ranges label
+ * below the lower dot and above the upper dot.
+ *
+ * Respects the spec's label density setting the same way dot labels do:
+ * - 'all': show every label, skip collision detection
+ * - 'auto': collision detection drops overlapping labels
+ * - 'endpoints': first and last rows only
+ * - 'none': return empty array
+ */
+
+import type {
+  LabelCandidate,
+  LabelDensity,
+  NumberFormatter,
+  PointMark,
+  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 = 10;
+
+/** A start/end dot pair for one data row. */
+export interface RangeDotPair {
+  start: PointMark;
+  end: PointMark;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Format one endpoint value using the spec's label format/prefix. */
+function formatEndpoint(
+  value: unknown,
+  formatter: ((n: number) => string) | null,
+  prefix: string | undefined,
+): string | null {
+  const num = Number(value);
+  if (!Number.isFinite(num)) return null;
+  const text = formatter ? formatter(num) : formatLabelValue(num);
+  return prefix ? prefix + text : text;
+}
+
+/** Build one label candidate placed outside the range span. */
+function buildCandidate(
+  mark: PointMark,
+  text: string,
+  horizontal: boolean,
+  outerSide: 'min' | 'max',
+  index: number,
+): LabelCandidate {
+  const textWidth = estimateTextWidth(text, LABEL_FONT_SIZE, LABEL_FONT_WEIGHT);
+  const textHeight = LABEL_FONT_SIZE * 1.2;
+
+  let anchorX: number;
+  let anchorY: number;
+  if (horizontal) {
+    // 'min' dot: label to the left; 'max' dot: label to the right.
+    anchorX =
+      outerSide === 'min'
+        ? mark.cx - mark.r - LABEL_OFFSET - textWidth
+        : mark.cx + mark.r + LABEL_OFFSET;
+    anchorY = mark.cy - textHeight / 2;
+  } else {
+    // SVG y grows downward: the 'min' value dot sits lower, label below it.
+    anchorX = mark.cx - textWidth / 2;
+    anchorY =
+      outerSide === 'min'
+        ? mark.cy + mark.r + LABEL_OFFSET - textHeight / 2
+        : mark.cy - mark.r - LABEL_OFFSET - textHeight / 2;
+  }
+
+  return {
+    text,
+    anchorX,
+    anchorY,
+    width: textWidth,
+    height: textHeight,
+    priority: 'data',
+    index,
+    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',
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute both-end value labels for dumbbell range marks.
+ *
+ * Each returned label carries `index` = pairIndex * 2 (start dot) or
+ * pairIndex * 2 + 1 (end dot) so the caller can attach labels back onto the
+ * right dot marks after density filtering. Labels dropped by collision
+ * resolution come back with `visible: false`.
+ */
+export function computeRangeLabels(
+  pairs: RangeDotPair[],
+  horizontal: boolean,
+  density: LabelDensity = 'auto',
+  labelPrefix?: string,
+  labelFormatter?: NumberFormatter | null,
+  startField?: string,
+  endField?: string,
+): ResolvedLabel[] {
+  if (density === 'none' || !startField || !endField) return [];
+
+  const indexed = pairs.map((pair, pairIndex) => ({ pair, pairIndex }));
+  const targetPairs = filterByDensity(indexed, density);
+  const formatter = labelFormatter ?? null;
+  const candidates: LabelCandidate[] = [];
+
+  for (const { pair, pairIndex } of targetPairs) {
+    const startText = formatEndpoint(pair.start.data[startField], formatter, labelPrefix);
+    const endText = formatEndpoint(pair.end.data[endField], formatter, labelPrefix);
+    if (startText == null || endText == null) continue;
+
+    // Place each label on the outer side of its dot. For horizontal ranges
+    // the lower pixel position is the left dot; vertical is inverted (SVG y
+    // grows downward), so the larger cy is the lower-value dot.
+    const startIsMin = horizontal ? pair.start.cx <= pair.end.cx : pair.start.cy >= pair.end.cy;
+    candidates.push(
+      buildCandidate(pair.start, startText, horizontal, startIsMin ? 'min' : 'max', pairIndex * 2),
+      buildCandidate(pair.end, endText, horizontal, startIsMin ? 'max' : 'min', pairIndex * 2 + 1),
+    );
+  }
+
+  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,
+      index: c.index,
+    }));
+  }
+
+  return resolveCollisions(candidates);
+}

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

@@ -0,0 +1,120 @@
+import type { RectMark } from '@opendata-ai/openchart-core';
+import { describe, expect, it } from 'vitest';
+import { compileChart } from '../../../compile';
+
+/** A 3x2 day/hour grid with a quantitative value: the canonical heatmap shape. */
+const grid = [
+  { day: 'Mon', hour: '9am', v: 3 },
+  { day: 'Mon', hour: '10am', v: 7 },
+  { day: 'Tue', hour: '9am', v: 5 },
+  { day: 'Tue', hour: '10am', v: 9 },
+  { day: 'Wed', hour: '9am', v: 1 },
+  { day: 'Wed', hour: '10am', v: 4 },
+];
+
+function heatmap(data = grid) {
+  return {
+    mark: { type: 'rect' as const },
+    data: [...data],
+    encoding: {
+      x: { field: 'day', type: 'nominal' as const },
+      y: { field: 'hour', type: 'nominal' as const },
+      color: { field: 'v', type: 'quantitative' as const },
+    },
+  };
+}
+
+function cellsOf(spec: Parameters<typeof compileChart>[0]): RectMark[] {
+  const layout = compileChart(spec, { width: 600, height: 400 });
+  return layout.marks.filter((m): m is RectMark => m.type === 'rect');
+}
+
+describe('rect mark (heatmap)', () => {
+  /**
+   * Regression: `rect` used to alias `columnRenderer`, which requires a *linear*
+   * y-scale (it anchors cells to `yScale(0)`). A heatmap bands both axes, so the
+   * renderer hit its bandwidth guard and returned []. `mark: 'rect'` rendered a
+   * blank chart with no error.
+   */
+  it('emits one cell per row instead of a blank chart', () => {
+    const cells = cellsOf(heatmap());
+    expect(cells).toHaveLength(grid.length);
+  });
+
+  it('gives every cell a positive width and height', () => {
+    for (const cell of cellsOf(heatmap())) {
+      expect(cell.width).toBeGreaterThan(0);
+      expect(cell.height).toBeGreaterThan(0);
+    }
+  });
+
+  it('tiles cells into a grid: one distinct x per day, one distinct y per hour', () => {
+    const cells = cellsOf(heatmap());
+    expect(new Set(cells.map((c) => c.x)).size).toBe(3); // Mon/Tue/Wed
+    expect(new Set(cells.map((c) => c.y)).size).toBe(2); // 9am/10am
+  });
+
+  it('colors cells from the quantitative color scale, not a flat default', () => {
+    const fills = new Set(cellsOf(heatmap()).map((c) => String(c.fill)));
+    // Six distinct values -> a sequential ramp must produce more than one color.
+    expect(fills.size).toBeGreaterThan(1);
+  });
+
+  it('keys each cell on its x/y pair so updates match by cell', () => {
+    const keys = cellsOf(heatmap()).map((c) => c.key);
+    expect(new Set(keys).size).toBe(grid.length);
+  });
+
+  it('skips rows whose color value is not finite', () => {
+    const cells = cellsOf(
+      heatmap([...grid, { day: 'Thu', hour: '9am', v: Number.NaN as unknown as number }]),
+    );
+    expect(cells).toHaveLength(grid.length);
+  });
+
+  /**
+   * Cells tile. The band default (0.35) is a *bar* value -- bars need air
+   * between them to read as separate quantities -- and it left the heatmap
+   * looking like a scatter of floating rectangles. A cell gap should be a
+   * hairline gutter, so each cell claims nearly its whole step.
+   */
+  it('tiles cells with only a hairline gutter, not a bar-sized gap', () => {
+    const cells = cellsOf(heatmap());
+    const xs = [...new Set(cells.map((c) => c.x))].sort((a, b) => a - b);
+    const step = xs[1] - xs[0];
+    const cellWidth = cells[0].width;
+    // Cell fills at least 90% of its step (0.35 padding would give ~65%).
+    expect(cellWidth / step).toBeGreaterThan(0.9);
+  });
+
+  it('draws no gridlines: the cells are the grid', () => {
+    const layout = compileChart(heatmap(), { width: 600, height: 400 });
+    expect(layout.axes.y?.gridlines ?? []).toHaveLength(0);
+  });
+
+  /**
+   * A quantitative axis has no bandwidth, so a cell has no width. Emitting
+   * zero-area marks would render an invisible chart -- the exact failure this
+   * renderer exists to end. Bail instead of pretending.
+   */
+  it('emits nothing when an axis is quantitative (no bandwidth to size a cell)', () => {
+    const cells = cellsOf({
+      mark: { type: 'rect' as const },
+      data: [...grid],
+      encoding: {
+        x: { field: 'v', type: 'quantitative' as const },
+        y: { field: 'hour', type: 'nominal' as const },
+        color: { field: 'v', type: 'quantitative' as const },
+      },
+    });
+    expect(cells).toHaveLength(0);
+  });
+
+  it('labels each cell with its x, y, and value for screen readers', () => {
+    const cells = cellsOf(heatmap());
+    const mon9 = cells.find((c) => c.data?.day === 'Mon' && c.data?.hour === '9am');
+    expect(mon9?.aria.label).toContain('Mon');
+    expect(mon9?.aria.label).toContain('9am');
+    expect(mon9?.aria.label).toContain('3');
+  });
+});